onbuzz 4.9.1 → 4.9.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "onbuzz",
-  "version": "4.9.1",
+  "version": "4.9.5",
   "description": "Loxia OnBuzz - Your AI Fleet",
   "type": "module",
   "main": "src/index.js",

package/src/__test-utils__/mockFactories.js

@@ -58,6 +58,8 @@ export function createMockStateManager() {
     initialize: jest.fn().mockResolvedValue(undefined),
     initializeStateDirectory: jest.fn().mockResolvedValue(undefined),
     persistAgentState: jest.fn().mockResolvedValue(undefined),
+    deleteAgentState: jest.fn().mockResolvedValue(undefined),
+    removeFromAgentIndex: jest.fn().mockResolvedValue(undefined),
     getProjectState: jest.fn().mockResolvedValue({}),
     loadProjectState: jest.fn().mockResolvedValue({}),
     saveProjectState: jest.fn().mockResolvedValue(undefined),

package/src/core/__tests__/agentPool.test.js

@@ -266,8 +266,28 @@ describe('AgentPool', () => {
       expect(await pool.getAgent(agent.id)).toBeNull();
     });
 
-    test('throws for non-existent agent', async () => {
-      await expect(pool.deleteAgent('nonexistent')).rejects.toThrow('Agent not found');
+    // Was: 'throws for non-existent agent'. The contract changed —
+    // deleteAgent is now idempotent so the bulk-delete UX can wipe
+    // unloaded agents (the My Squadron group-delete used to fail with
+    // "Failed to delete N agents" whenever any target wasn't in memory).
+    // deleteAgentState is itself ENOENT-tolerant, so "not in pool, not
+    // on disk" still resolves to success — same end state.
+    test('is idempotent for an agent not in the pool (succeeds, clears persistent state)', async () => {
+      stateManager.deleteAgentState.mockClear();
+      const result = await pool.deleteAgent('nonexistent-agent-id');
+      expect(result.success).toBe(true);
+      // Still asked the state manager to clear it — best-effort cleanup.
+      expect(stateManager.deleteAgentState).toHaveBeenCalledWith('nonexistent-agent-id');
+    });
+
+    test('removes persistent state even when the agent was never loaded', async () => {
+      // Simulate an agent that exists on disk but isn't in memory
+      // (e.g. process restarted, or it was unloaded earlier).
+      stateManager.deleteAgentState.mockClear();
+      // No createAgent — pool.agents stays empty.
+      const result = await pool.deleteAgent('unloaded-but-on-disk');
+      expect(result.success).toBe(true);
+      expect(stateManager.deleteAgentState).toHaveBeenCalledWith('unloaded-but-on-disk');
     });
 
     test('cleans up maps (directory, paused, notification)', async () => {

package/src/core/agentPool.js

@@ -868,74 +868,86 @@ class AgentPool {
    */
 
   /**
-   * Delete an agent and clean up its resources
+   * Delete an agent and clean up its resources.
+   *
+   * Best-effort / idempotent: if the agent isn't currently loaded in
+   * memory we skip the live-state cleanup (attachments, visual editor,
+   * terminal processes — those only exist for loaded agents anyway)
+   * and go straight to clearing persistent state. This is how the
+   * bulk-delete UI can remove agents that were unloaded earlier in
+   * the session or that survived a process restart with no in-memory
+   * footprint. `stateManager.deleteAgentState` is itself ENOENT-safe,
+   * so deleting an already-gone agent is a no-op success.
+   *
    * @param {string} agentId - Agent identifier
    * @returns {Promise<Object>} Deletion result
    */
   async deleteAgent(agentId) {
     const agent = await this.getAgent(agentId);
-    if (!agent) {
-      throw new Error(`Agent not found: ${agentId}`);
-    }
+    const wasLoaded = !!agent;
 
-    // Clean up file attachments with reference counting
-    if (this.fileAttachmentService) {
-      try {
-        await this.fileAttachmentService.deleteAgentAttachments(agentId);
-        this.logger.info(`File attachments cleaned up for agent: ${agentId}`);
-      } catch (error) {
-        this.logger.warn(`Failed to clean up file attachments for agent: ${error.message}`, { agentId });
-        // Continue with agent deletion even if attachment cleanup fails
+    if (wasLoaded) {
+      // Clean up file attachments with reference counting
+      if (this.fileAttachmentService) {
+        try {
+          await this.fileAttachmentService.deleteAgentAttachments(agentId);
+          this.logger.info(`File attachments cleaned up for agent: ${agentId}`);
+        } catch (error) {
+          this.logger.warn(`Failed to clean up file attachments for agent: ${error.message}`, { agentId });
+          // Continue with agent deletion even if attachment cleanup fails
+        }
       }
-    }
 
-    // Clear codebase-knowledge cache for this agent — bytes live in
-    // the service's in-memory map; without this the per-agent entry
-    // would persist until the next process restart.
-    try {
-      const { getCodebaseKnowledgeService } = await import('../services/codebaseKnowledgeService.js');
-      getCodebaseKnowledgeService(this.logger).clear(agentId);
-    } catch (e) {
-      this.logger.debug?.('codebase-knowledge clear failed on agent delete', { agentId, error: e.message });
-    }
+      // Clear codebase-knowledge cache for this agent — bytes live in
+      // the service's in-memory map; without this the per-agent entry
+      // would persist until the next process restart.
+      try {
+        const { getCodebaseKnowledgeService } = await import('../services/codebaseKnowledgeService.js');
+        getCodebaseKnowledgeService(this.logger).clear(agentId);
+      } catch (e) {
+        this.logger.debug?.('codebase-knowledge clear failed on agent delete', { agentId, error: e.message });
+      }
 
-    // Clean up visual editor instance
-    try {
-      const visualEditorBridge = getVisualEditorBridge();
-      if (visualEditorBridge.hasInstance(agentId)) {
-        await visualEditorBridge.stopInstance(agentId);
-        this.logger.info(`Visual editor instance cleaned up for agent: ${agentId}`);
+      // Clean up visual editor instance
+      try {
+        const visualEditorBridge = getVisualEditorBridge();
+        if (visualEditorBridge.hasInstance(agentId)) {
+          await visualEditorBridge.stopInstance(agentId);
+          this.logger.info(`Visual editor instance cleaned up for agent: ${agentId}`);
+        }
+      } catch (error) {
+        this.logger.warn(`Failed to clean up visual editor for agent: ${error.message}`, { agentId });
       }
-    } catch (error) {
-      this.logger.warn(`Failed to clean up visual editor for agent: ${error.message}`, { agentId });
-    }
 
-    // Kill any running terminal processes for this agent
-    try {
-      const terminalTool = this.toolsRegistry?.getTool?.('terminal');
-      if (terminalTool && typeof terminalTool.cleanupAgent === 'function') {
-        await terminalTool.cleanupAgent(agentId);
-        this.logger.info(`Terminal processes cleaned up for agent: ${agentId}`);
+      // Kill any running terminal processes for this agent
+      try {
+        const terminalTool = this.toolsRegistry?.getTool?.('terminal');
+        if (terminalTool && typeof terminalTool.cleanupAgent === 'function') {
+          await terminalTool.cleanupAgent(agentId);
+          this.logger.info(`Terminal processes cleaned up for agent: ${agentId}`);
+        }
+      } catch (error) {
+        this.logger.warn(`Failed to clean up terminal processes for agent: ${error.message}`, { agentId });
       }
-    } catch (error) {
-      this.logger.warn(`Failed to clean up terminal processes for agent: ${error.message}`, { agentId });
+
+      // Clean up agent resources
+      this.agents.delete(agentId);
+      this.agentDirectory.delete(agentId);
+      this.pausedAgents.delete(agentId);
+      this.notificationQueue.delete(agentId);
     }
 
-    // Clean up agent resources
-    this.agents.delete(agentId);
-    this.agentDirectory.delete(agentId);
-    this.pausedAgents.delete(agentId);
-    this.notificationQueue.delete(agentId);
-    
-    // Clean up persistent state
+    // Clean up persistent state — runs whether or not the agent was
+    // loaded. deleteAgentState handles missing files gracefully.
     try {
       await this.stateManager.deleteAgentState(agentId);
     } catch (error) {
       this.logger.warn(`Failed to delete agent persistent state: ${error.message}`, { agentId });
     }
-    
+
     this.logger.info(`Agent deleted: ${agentId}`, {
-      agentName: agent.name,
+      agentName: agent?.name || '(not loaded)',
+      wasLoaded,
       totalAgents: this.agents.size
     });
     

package/src/core/orchestrator.js

@@ -326,30 +326,31 @@ class Orchestrator {
    */
   async _handleDeleteAgent(request) {
     const { agentId } = request.payload;
-    
+
     if (!agentId) {
       throw new Error('Agent ID is required for deletion');
     }
-    
-    // Get agent before deletion to return info
+
+    // Best-effort lookup for logging + response shape. We do NOT throw
+    // when the agent isn't loaded — that breaks bulk-delete against
+    // agents that were unloaded earlier in the session (the original
+    // implementation made the entire group operation fail with
+    // "Failed to delete N agents"). agentPool.deleteAgent now handles
+    // the unloaded case by cleaning up persistent state only.
     const agent = await this.agentPool.getAgent(agentId);
-    if (!agent) {
-      throw new Error(`Agent not found: ${agentId}`);
-    }
-    
-    // Delete the agent
+
     const result = await this.agentPool.deleteAgent(agentId);
-    
+
     this.logger.info(`Agent deleted: ${agentId}`, {
-      agentName: agent.name,
+      agentName: agent?.name || '(not loaded)',
       sessionId: request.sessionId
     });
-    
+
     return {
       success: true,
       deletedAgent: {
-        id: agent.id,
-        name: agent.name
+        id: agentId,
+        name: agent?.name || null,
       },
       ...result
     };

package/src/interfaces/__tests__/bulkAgentRoute.test.js

@@ -59,7 +59,7 @@ function bulkHandler(orchestrator, logger) {
           if (!agent && action !== 'delete') return { agentId, success: false, error: 'Agent not found' };
           if (actionMap[action]) {
             const payload = action === 'set-model' ? { agentId, model: params.model } : { agentId };
-            const r = await orchestrator.processRequest({ sessionId: effectiveSessionId, interface: 'WEB', action: actionMap[action], payload, projectDir });
+            const r = await orchestrator.processRequest({ sessionId: effectiveSessionId, interface: 'web', action: actionMap[action], payload, projectDir });
             return { agentId, success: r?.success !== false, error: r?.error || null };
           }
           if (action === 'enable-tool' || action === 'disable-tool') {
@@ -69,7 +69,7 @@ function bulkHandler(orchestrator, logger) {
             const i = caps.indexOf(tool);
             if (action === 'enable-tool' && i === -1) caps.push(tool);
             if (action === 'disable-tool' && i !== -1) caps.splice(i, 1);
-            const r = await orchestrator.processRequest({ sessionId: effectiveSessionId, interface: 'WEB', action: 'update_agent', payload: { agentId, updates: { capabilities: caps } }, projectDir });
+            const r = await orchestrator.processRequest({ sessionId: effectiveSessionId, interface: 'web', action: 'update_agent', payload: { agentId, updates: { capabilities: caps } }, projectDir });
             return { agentId, success: r?.success !== false, error: r?.error || null };
           }
           if (action === 'archive') {
@@ -77,7 +77,7 @@ function bulkHandler(orchestrator, logger) {
               await orchestrator.stateManager.archiveAgent(agentId, projectDir);
               return { agentId, success: true };
             }
-            const r = await orchestrator.processRequest({ sessionId: effectiveSessionId, interface: 'WEB', action: 'unload_agent', payload: { agentId }, projectDir });
+            const r = await orchestrator.processRequest({ sessionId: effectiveSessionId, interface: 'web', action: 'unload_agent', payload: { agentId }, projectDir });
             return { agentId, success: r?.success !== false, error: r?.error || null };
           }
           return { agentId, success: false, error: `Unhandled action: ${action}` };
@@ -287,4 +287,75 @@ describe('POST /api/agents/bulk — partial success', () => {
     expect(r.body.summary).toEqual({ total: 2, ok: 1, failed: 1 });
     expect(r.body.results.find(x => x.agentId === 'missing-1').error).toMatch(/not found/i);
   });
+
+  // Regression guard for the silent "Invalid interface: WEB" bug.
+  //
+  // The bulk handler used to hardcode `interface: 'WEB'` (uppercase),
+  // but orchestrator.processRequest validates against INTERFACE_TYPES
+  // — which uses LOWERCASE strings ('web', 'cli', etc.). Every bulk
+  // action — delete, pause, resume, unload, set-model, enable-tool,
+  // disable-tool, archive — failed with `Invalid interface: WEB`
+  // before even dispatching. The error was caught in `runOne`'s
+  // try/catch and surfaced as per-agent failure ("Failed to delete
+  // N agents") with no hint at the actual cause.
+  //
+  // Lock the lowercase contract for every action that flows through
+  // processRequest, so any case-drift trips this test immediately.
+  it('forwards lowercase "web" as the interface (not "WEB") for every dispatch', async () => {
+    orch = makeOrchestrator();
+    await startServer(orch);
+    // Hit one representative of each routed action.
+    await post({ action: 'delete', agentIds: ['a'] });
+    await post({ action: 'pause',  agentIds: ['a'] });
+    await post({ action: 'unload', agentIds: ['a'] });
+    await post({ action: 'set-model', agentIds: ['a'], params: { model: 'k' } });
+
+    // Every call to processRequest must have used lowercase 'web'.
+    for (const call of orch.processRequest.mock.calls) {
+      expect(call[0].interface).toBe('web');
+    }
+  });
+
+  it('falls flat if the orchestrator rejects "WEB" — regression of the original bug', async () => {
+    // Simulate the real orchestrator's validation: throw on anything
+    // not matching INTERFACE_TYPES.WEB ('web'). With the fix, every
+    // call should succeed because the handler now passes lowercase.
+    orch = makeOrchestrator({
+      processRequest: jest.fn(async ({ interface: iface }) => {
+        if (iface !== 'web') throw new Error(`Invalid interface: ${iface}`);
+        return { success: true };
+      }),
+    });
+    await startServer(orch);
+    const r = await post({ action: 'delete', agentIds: ['a', 'b'] });
+    expect(r.body.success).toBe(true);
+    expect(r.body.summary).toEqual({ total: 2, ok: 2, failed: 0 });
+  });
+
+  // Regression guard for the My Squadron > group operation (delete) bug.
+  // Before the fix, deleting selected agents in the UI failed with
+  // "Failed to delete N agents" whenever any of them was unloaded —
+  // the bulk handler let `delete` flow through to the orchestrator, but
+  // the orchestrator's _handleDeleteAgent threw "Agent not found" for
+  // anything not in the live pool. Now agentPool.deleteAgent is
+  // idempotent (clears persistent state regardless of pool membership)
+  // and the orchestrator surfaces that success up through processRequest.
+  // From the bulk route's perspective: every missing-prefixed agent
+  // should report success.
+  it('delete against missing/unloaded agents succeeds (idempotent cleanup)', async () => {
+    orch = makeOrchestrator();
+    await startServer(orch);
+    const r = await post({ action: 'delete', agentIds: ['missing-1', 'missing-2', 'a'] });
+    expect(r.status).toBe(200);
+    expect(r.body.success).toBe(true);
+    expect(r.body.summary).toEqual({ total: 3, ok: 3, failed: 0 });
+    // All three reached processRequest (no short-circuit on missing).
+    expect(orch.processRequest).toHaveBeenCalledTimes(3);
+    for (const id of ['missing-1', 'missing-2', 'a']) {
+      expect(orch.processRequest).toHaveBeenCalledWith(expect.objectContaining({
+        action: 'delete_agent',
+        payload: expect.objectContaining({ agentId: id }),
+      }));
+    }
+  });
 });

package/src/interfaces/webServer.js

@@ -4817,15 +4817,17 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
           try {
             const agent = await this.orchestrator.agentPool.getAgent(agentId).catch(() => null);
             if (!agent && action !== 'delete') {
-              // Allow `delete` to proceed against missing agents
-              // (idempotent cleanup); other actions need the agent loaded.
+              // `delete` flows through to agentPool.deleteAgent which
+              // handles both loaded and unloaded agents (clears
+              // persistent state in either case). Other actions need
+              // a live agent instance to mutate, so we short-circuit.
               return { agentId, success: false, error: 'Agent not found' };
             }
 
             switch (action) {
               case 'delete': {
                 const r = await this.orchestrator.processRequest({
-                  sessionId: effectiveSessionId, interface: 'WEB',
+                  sessionId: effectiveSessionId, interface: INTERFACE_TYPES.WEB,
                   action: 'delete_agent',
                   payload: { agentId },
                   projectDir,
@@ -4834,7 +4836,7 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
               }
               case 'unload': {
                 const r = await this.orchestrator.processRequest({
-                  sessionId: effectiveSessionId, interface: 'WEB',
+                  sessionId: effectiveSessionId, interface: INTERFACE_TYPES.WEB,
                   action: 'unload_agent',
                   payload: { agentId },
                   projectDir,
@@ -4843,7 +4845,7 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
               }
               case 'pause': {
                 const r = await this.orchestrator.processRequest({
-                  sessionId: effectiveSessionId, interface: 'WEB',
+                  sessionId: effectiveSessionId, interface: INTERFACE_TYPES.WEB,
                   action: 'pause_agent',
                   payload: { agentId },
                   projectDir,
@@ -4852,7 +4854,7 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
               }
               case 'resume': {
                 const r = await this.orchestrator.processRequest({
-                  sessionId: effectiveSessionId, interface: 'WEB',
+                  sessionId: effectiveSessionId, interface: INTERFACE_TYPES.WEB,
                   action: 'resume_agent',
                   payload: { agentId },
                   projectDir,
@@ -4861,7 +4863,7 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
               }
               case 'set-model': {
                 const r = await this.orchestrator.processRequest({
-                  sessionId: effectiveSessionId, interface: 'WEB',
+                  sessionId: effectiveSessionId, interface: INTERFACE_TYPES.WEB,
                   action: 'switch_model',
                   payload: { agentId, model: params.model },
                   projectDir,
@@ -4878,7 +4880,7 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
                 if (action === 'enable-tool' && i === -1) caps.push(tool);
                 if (action === 'disable-tool' && i !== -1) caps.splice(i, 1);
                 const r = await this.orchestrator.processRequest({
-                  sessionId: effectiveSessionId, interface: 'WEB',
+                  sessionId: effectiveSessionId, interface: INTERFACE_TYPES.WEB,
                   action: 'update_agent',
                   payload: { agentId, updates: { capabilities: caps } },
                   projectDir,
@@ -4894,7 +4896,7 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
                   return { agentId, success: true };
                 }
                 const r = await this.orchestrator.processRequest({
-                  sessionId: effectiveSessionId, interface: 'WEB',
+                  sessionId: effectiveSessionId, interface: INTERFACE_TYPES.WEB,
                   action: 'unload_agent',
                   payload: { agentId },
                   projectDir,

package/src/tools/office/pres/archetypes/_helpers.js

@@ -0,0 +1,92 @@
+/**
+ * Shared archetype helpers — text placement, footer chrome,
+ * rule lines, callout cards. Every archetype reuses these so styling
+ * stays consistent across slide types.
+ */
+import { textStyle } from '../typography.js';
+import { cardShape, shapeOpts } from '../shapes.js';
+import { applyBackground } from '../backgrounds/index.js';
+
+/**
+ * Apply background + optional decorative chrome shared across all
+ * archetypes (e.g. footer rule, slide number).
+ *
+ *   - `bgOverride` lets an individual archetype request a different
+ *     background style than the theme default (the hero archetype in
+ *     tech-bold always wants `mesh` even if the deck default is solid).
+ *   - `seed` is forwarded so deterministic generators (mesh) place
+ *     their blobs consistently per slide.
+ */
+export function applyChrome(slide, resolved, { bgOverride, seed, footer } = {}) {
+  applyBackground(slide, resolved, bgOverride || resolved.bg, { seed });
+
+  if (footer && footer.text) {
+    slide.addText(footer.text, {
+      x: resolved.spacing.safe.x,
+      y: resolved.spacing.slide.height - resolved.spacing.pageMargin - 0.3,
+      w: resolved.spacing.safe.w,
+      h: 0.3,
+      ...textStyle(resolved.typography, 'caption', {
+        color: resolved.palette.subtle,
+        align: footer.align || 'left',
+      }),
+    });
+  }
+}
+
+/** Draw a single horizontal accent rule at (x, y, w). */
+export function rule(slide, x, y, w, color, weight = 1) {
+  slide.addShape('line', {
+    x, y, w, h: 0,
+    line: { color, width: weight },
+  });
+}
+
+/** Draw a small uppercase eyebrow label above a title block. */
+export function eyebrow(slide, resolved, text, { x, y, w, color }) {
+  slide.addText(String(text || '').toUpperCase(), {
+    x, y, w, h: 0.25,
+    ...textStyle(resolved.typography, 'eyebrow', {
+      color: color || resolved.palette.primary,
+      align: 'left',
+    }),
+  });
+}
+
+/** Place a single block of text — wraps {@link textStyle} for brevity. */
+export function placeText(slide, resolved, role, text, frame, overrides = {}) {
+  if (text === undefined || text === null || text === '') return;
+  slide.addText(String(text), {
+    ...frame,
+    ...textStyle(resolved.typography, role, overrides),
+  });
+}
+
+/** Place a stack of bullet items into a frame. */
+export function placeBullets(slide, resolved, items, frame, overrides = {}) {
+  const rows = (items || []).map((li) => {
+    const text = typeof li === 'string' ? li : (li.text || '');
+    const bullet = (typeof li === 'object' && li.bullet === false)
+      ? false
+      : { type: (typeof li === 'object' && li.ordered) ? 'number' : 'bullet' };
+    return { text, options: { bullet } };
+  });
+  slide.addText(rows, {
+    ...frame,
+    ...textStyle(resolved.typography, 'body', { color: resolved.palette.text, ...overrides }),
+    paraSpaceAfter: resolved.spacing.paragraphGap * 8, // pptxgenjs unit ≈ point
+  });
+}
+
+/**
+ * Draw a "callout card" — a filled rectangle with optional shadow
+ * and the active shape's corner radius. Used to wrap stat numbers,
+ * data tables, charts on `tech-bold`.
+ */
+export function callout(slide, resolved, frame, fillColor) {
+  const opts = shapeOpts(resolved.shape, 'card', fillColor || resolved.palette.surface);
+  slide.addShape(cardShape(resolved.shape), {
+    x: frame.x, y: frame.y, w: frame.w, h: frame.h,
+    ...opts,
+  });
+}

package/src/tools/office/pres/archetypes/agenda.js

@@ -0,0 +1,61 @@
+/**
+ * Archetype: agenda — numbered list of sections the deck will cover.
+ *
+ * Slots:
+ *   - title  (optional, default "Agenda")
+ *   - items  (required) array of strings or { title, hint } objects
+ *
+ * Numbers are rendered in display-weight; titles in body weight; hints
+ * (when present) in caption colour. Density depends on the spacing
+ * preset — `tight` allows ~10 items, `airy` ~6.
+ */
+import { applyChrome, placeText } from './_helpers.js';
+import { textStyle } from '../typography.js';
+
+export const id = 'agenda';
+export const slots = ['title', 'items'];
+
+export default function render(slide, resolved, content) {
+  applyChrome(slide, resolved, { bgOverride: content.background, seed: 7 });
+
+  const { safe, header, body } = resolved.spacing;
+
+  placeText(slide, resolved, 'title', content.title || 'Agenda', {
+    x: header.x, y: header.y, w: header.w, h: header.h,
+  }, { color: resolved.palette.text, align: 'left' });
+
+  const items = Array.isArray(content.items) ? content.items : [];
+  const n = items.length || 1;
+  const rowH = Math.min(0.9, body.h / Math.max(n, 4));
+
+  items.forEach((raw, i) => {
+    const item = typeof raw === 'string' ? { title: raw } : raw;
+    const y = body.y + i * rowH;
+
+    // Number column
+    slide.addText(String(i + 1).padStart(2, '0'), {
+      x: body.x, y, w: 0.9, h: rowH,
+      ...textStyle(resolved.typography, 'title', {
+        color: resolved.palette.subtle, align: 'left', valign: 'middle',
+      }),
+    });
+
+    // Title column
+    slide.addText(item.title || '', {
+      x: body.x + 1.1, y, w: body.w - 1.1, h: rowH * 0.55,
+      ...textStyle(resolved.typography, 'subtitle', {
+        color: resolved.palette.text, align: 'left', valign: 'middle', bold: true,
+      }),
+    });
+
+    // Hint column (optional, shown beneath title)
+    if (item.hint) {
+      slide.addText(item.hint, {
+        x: body.x + 1.1, y: y + rowH * 0.5, w: body.w - 1.1, h: rowH * 0.5,
+        ...textStyle(resolved.typography, 'caption', {
+          color: resolved.palette.subtle, align: 'left', valign: 'top',
+        }),
+      });
+    }
+  });
+}

package/src/tools/office/pres/archetypes/hero.js

@@ -0,0 +1,69 @@
+/**
+ * Archetype: hero — title slide opening a deck.
+ *
+ * Slots:
+ *   - eyebrow   (optional) small uppercase label above title
+ *   - title     (required) huge display text — the deck's name
+ *   - subtitle  (optional) supporting line below title
+ *   - author    (optional) presenter name in footer
+ *   - date      (optional) date string in footer
+ *   - background (optional) per-slide bg override; defaults to theme.bg
+ *
+ * Layout is left-aligned by default; theme `archetypes.hero.align`
+ * can switch to 'center'. Tech-bold likes the eyebrow rendered in
+ * accent colour; editorial puts a hairline rule under the eyebrow.
+ */
+import { applyChrome, eyebrow, placeText, rule } from './_helpers.js';
+
+export const id = 'hero';
+export const slots = ['eyebrow', 'title', 'subtitle', 'author', 'date'];
+
+export default function render(slide, resolved, content, _pptx) {
+  applyChrome(slide, resolved, { bgOverride: content.background, seed: 11 });
+
+  const cfg = resolved.archetypeConfig('hero');
+  const align = cfg.align || 'left';
+  const { safe, body } = resolved.spacing;
+
+  // Title block roughly vertically centered in the body region but
+  // weighted up slightly so subtitle + footer have breathing room.
+  const titleY = safe.y + safe.h * 0.32;
+  const titleFrame = { x: safe.x, y: titleY, w: safe.w, h: 2 };
+
+  if (content.eyebrow) {
+    const ebColor = cfg.eyebrowOnAccent ? resolved.palette.accent : resolved.palette.primary;
+    eyebrow(slide, resolved, content.eyebrow, {
+      x: safe.x, y: titleY - 0.5, w: safe.w / 2, color: ebColor,
+    });
+    if (cfg.eyebrowDivider) {
+      rule(slide, safe.x, titleY - 0.18, 0.6, ebColor, 1);
+    }
+  }
+
+  placeText(slide, resolved, 'display', content.title, titleFrame, {
+    color: resolved.palette.text,
+    align,
+    valign: 'top',
+    fit: 'shrink',
+  });
+
+  if (content.subtitle) {
+    placeText(slide, resolved, 'subtitle', content.subtitle, {
+      x: safe.x, y: titleY + 1.9, w: safe.w * 0.78, h: 1.2,
+    }, {
+      color: resolved.palette.subtle,
+      align,
+    });
+  }
+
+  // Footer: author · date, on a single line, subtle colour, hairline above.
+  const footerY = resolved.spacing.slide.height - resolved.spacing.pageMargin - 0.5;
+  if (content.author || content.date) {
+    const parts = [content.author, content.date].filter(Boolean).join('  ·  ');
+    placeText(slide, resolved, 'caption', parts, {
+      x: safe.x, y: footerY, w: safe.w, h: 0.3,
+    }, { color: resolved.palette.subtle, align: 'left' });
+
+    rule(slide, safe.x, footerY - 0.08, 0.6, resolved.palette.primary, 1);
+  }
+}