@pellux/goodvibes-agent 1.5.5 → 1.5.6

package/src/cli/personas-command.ts

@@ -0,0 +1,252 @@
+import { discoverPersonas, type DiscoveredPersonaRecord } from '../agent/persona-discovery.ts';
+import type { AgentPersonaRecord } from '../agent/persona-registry.ts';
+import { formatAgentRecordOrigin, formatAgentRecordReviewState } from '../agent/record-labels.ts';
+import type { CliCommandOutput } from './types.ts';
+import type { CliCommandRuntime } from './management.ts';
+import {
+  csvOption,
+  errorOutput,
+  failure,
+  hasFlag,
+  optionValue,
+  parseOptions,
+  personaRegistry,
+  requiredOption,
+  shellPaths,
+  success,
+} from './local-library-command-shared.ts';
+
+function summarizePersona(persona: AgentPersonaRecord, activePersonaId: string | null): string {
+  const active = persona.id === activePersonaId ? 'active' : 'available';
+  const tags = persona.tags.length > 0 ? `  tags ${persona.tags.join(', ')}` : '';
+  return `  ${persona.id}  ${active}  ${formatAgentRecordReviewState(persona.reviewState)}  ${persona.name} - ${persona.description}${tags}`;
+}
+
+function renderPersonaList(title: string, path: string, personas: readonly AgentPersonaRecord[], activePersonaId: string | null): string {
+  if (personas.length === 0) {
+    return [
+      title,
+      '  No local Agent personas yet. Create one with: goodvibes-agent personas create --name <name> --description <summary> --body <instructions>',
+    ].join('\n');
+  }
+  return [
+    `${title} (${personas.length})`,
+    `  store ${path}`,
+    ...personas.map((persona) => summarizePersona(persona, activePersonaId)),
+  ].join('\n');
+}
+
+function renderPersona(persona: AgentPersonaRecord, activePersonaId: string | null): string {
+  return [
+    `Persona ${persona.name}`,
+    `  id ${persona.id}`,
+    `  active: ${persona.id === activePersonaId ? 'yes' : 'no'}`,
+    `  review: ${formatAgentRecordReviewState(persona.reviewState)}`,
+    `  origin: ${formatAgentRecordOrigin(persona.source, persona.provenance)}`,
+    `  tags: ${persona.tags.join(', ') || '(none)'}`,
+    `  triggers: ${persona.triggers.join(', ') || '(manual)'}`,
+    `  created: ${persona.createdAt}`,
+    `  updated: ${persona.updatedAt}`,
+    persona.staleReason ? `  stale reason: ${persona.staleReason}` : '',
+    '',
+    persona.description,
+    '',
+    persona.body,
+  ].filter((line): line is string => Boolean(line)).join('\n');
+}
+
+function summarizeDiscoveredPersona(persona: DiscoveredPersonaRecord): string {
+  const description = persona.description ? ` - ${persona.description}` : '';
+  return [
+    `  ${persona.name}  ${persona.origin}${description}`,
+    `    path ${persona.path}`,
+  ].join('\n');
+}
+
+function renderDiscoveredPersonaList(personas: readonly DiscoveredPersonaRecord[]): string {
+  if (personas.length === 0) {
+    return [
+      'Discovered Agent persona files',
+      '  No persona markdown files found in Agent persona folders.',
+      '  Search roots: .goodvibes/personas, .goodvibes/agent/personas, ~/.goodvibes/personas, ~/.goodvibes/agent/personas',
+    ].join('\n');
+  }
+  return [
+    `Discovered Agent persona files (${personas.length})`,
+    ...personas.map(summarizeDiscoveredPersona),
+    '',
+    'Import one with: goodvibes-agent personas import-discovered <name> --yes',
+  ].join('\n');
+}
+
+function discoveredPersonaLookupValues(persona: DiscoveredPersonaRecord): readonly string[] {
+  const slug = persona.name.trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  const basename = persona.path.split(/[\\/]/).pop()?.replace(/\.md$/i, '') ?? '';
+  return [persona.name, slug, persona.path, basename]
+    .map((value) => value.trim().toLowerCase())
+    .filter(Boolean);
+}
+
+function findDiscoveredPersona(personas: readonly DiscoveredPersonaRecord[], idOrName: string): DiscoveredPersonaRecord | null {
+  const lookup = idOrName.trim().toLowerCase();
+  if (!lookup) return null;
+  return personas.find((persona) => discoveredPersonaLookupValues(persona).includes(lookup)) ?? null;
+}
+
+function discoveredPersonaFrontmatterList(persona: DiscoveredPersonaRecord, key: string): readonly string[] {
+  const value = persona.frontmatter[key];
+  if (!value) return [];
+  return value.split(',').map((entry) => entry.trim()).filter(Boolean);
+}
+
+function usagePersonas(): string {
+  return 'Usage: goodvibes-agent personas [list|active|discover|import-discovered <name> --yes|search <query>|show <id>|create|update <id>|use <id>|clear|review <id>|stale <id> <reason>|delete <id> --yes]';
+}
+
+export async function handlePersonasCommand(runtime: CliCommandRuntime): Promise<CliCommandOutput> {
+  try {
+    const [sub = 'list', ...rest] = runtime.cli.commandArgs;
+    const normalized = sub.toLowerCase();
+    const registry = personaRegistry(runtime);
+    const snapshot = registry.snapshot();
+    if (normalized === 'list' || normalized === 'ls') {
+      return success(runtime, 'agent.personas.list', snapshot, renderPersonaList('Agent personas', snapshot.path, snapshot.personas, snapshot.activePersonaId));
+    }
+    if (normalized === 'active') {
+      const active = snapshot.activePersona;
+      if (!active) return failure(runtime, 'agent.personas.active_missing', 'No active Agent persona.', 1);
+      return success(runtime, 'agent.personas.active', active, renderPersona(active, active.id));
+    }
+    if (normalized === 'discover') {
+      const discovered = await discoverPersonas(shellPaths(runtime));
+      return success(runtime, 'agent.personas.discover', { personas: discovered }, renderDiscoveredPersonaList(discovered));
+    }
+    if (normalized === 'import-discovered' || normalized === 'import-persona') {
+      const options = parseOptions(rest);
+      const name = options.positionals.join(' ').trim();
+      if (!name) return failure(runtime, 'invalid_persona_command', 'Usage: goodvibes-agent personas import-discovered <name> [--use] --yes', 2);
+      const discovered = findDiscoveredPersona(await discoverPersonas(shellPaths(runtime)), name);
+      if (!discovered) {
+        return failure(runtime, 'persona_discovery_not_found', `Unknown discovered Agent persona ${name}\nRun goodvibes-agent personas discover to inspect available persona files.`, 1);
+      }
+      if (!hasFlag(options, 'yes')) {
+        return success(runtime, 'agent.personas.import_discovered.preview', { persona: discovered }, [
+          'Agent persona import preview',
+          `  name ${discovered.name}`,
+          `  origin ${discovered.origin}`,
+          `  path ${discovered.path}`,
+          `  description ${discovered.description || '(none)'}`,
+          `  body characters ${discovered.body.length}`,
+          '  next rerun with --yes to import into the Agent-local persona registry',
+        ].join('\n'));
+      }
+      const persona = registry.create({
+        name: discovered.name,
+        description: discovered.description || `Imported persona from ${discovered.origin} markdown file.`,
+        body: discovered.body,
+        tags: discoveredPersonaFrontmatterList(discovered, 'tags'),
+        triggers: discoveredPersonaFrontmatterList(discovered, 'triggers'),
+        source: 'imported',
+        provenance: `discovered:${discovered.origin}:${discovered.path}`,
+      });
+      if (hasFlag(options, 'use')) registry.setActive(persona.id);
+      return success(runtime, 'agent.personas.import_discovered', persona, [
+        `Imported Agent persona ${persona.id}: ${persona.name}${hasFlag(options, 'use') ? ' (active)' : ''}`,
+        `  name ${persona.name}`,
+        `  active ${hasFlag(options, 'use') ? 'yes' : 'no'}`,
+      ].join('\n'));
+    }
+    if (normalized === 'search' || normalized === 'find') {
+      const query = rest.join(' ').trim();
+      const results = registry.search(query);
+      return success(runtime, 'agent.personas.search', { query, results }, renderPersonaList(`Agent personas matching "${query}"`, snapshot.path, results, snapshot.activePersonaId));
+    }
+    if (normalized === 'show' || normalized === 'get') {
+      const id = rest[0];
+      if (!id) return failure(runtime, 'invalid_persona_command', 'Usage: goodvibes-agent personas show <id>', 2);
+      const persona = registry.get(id);
+      if (!persona) return failure(runtime, 'persona_not_found', `Unknown Agent persona ${id}`, 1);
+      return success(runtime, 'agent.personas.show', persona, renderPersona(persona, snapshot.activePersonaId));
+    }
+    if (normalized === 'create') {
+      const options = parseOptions(rest);
+      const persona = registry.create({
+        name: requiredOption(options, 'name', 'Usage: goodvibes-agent personas create --name <name> --description <summary> --body <instructions>'),
+        description: requiredOption(options, 'description', 'Usage: goodvibes-agent personas create --name <name> --description <summary> --body <instructions>'),
+        body: requiredOption(options, 'body', 'Usage: goodvibes-agent personas create --name <name> --description <summary> --body <instructions>'),
+        tags: csvOption(options, 'tags'),
+        triggers: csvOption(options, 'triggers'),
+        provenance: optionValue(options, 'provenance') ?? 'Command',
+      });
+      if (hasFlag(options, 'use')) registry.setActive(persona.id);
+      return success(runtime, 'agent.personas.create', persona, [
+        'Agent persona created',
+        `  id ${persona.id}`,
+        hasFlag(options, 'use') ? '  (active)' : '',
+        `  active ${hasFlag(options, 'use') ? 'yes' : 'no'}`,
+      ].filter(Boolean).join('\n'));
+    }
+    if (normalized === 'update') {
+      const id = rest[0];
+      if (!id) return failure(runtime, 'invalid_persona_command', 'Usage: goodvibes-agent personas update <id> [--name ...] [--description ...] [--body ...]', 2);
+      const options = parseOptions(rest.slice(1));
+      const persona = registry.update(id, {
+        name: optionValue(options, 'name'),
+        description: optionValue(options, 'description'),
+        body: optionValue(options, 'body'),
+        tags: csvOption(options, 'tags'),
+        triggers: csvOption(options, 'triggers'),
+        provenance: optionValue(options, 'provenance'),
+      });
+      return success(runtime, 'agent.personas.update', persona, [
+        'Agent persona updated',
+        `  id ${persona.id}`,
+      ].join('\n'));
+    }
+    if (normalized === 'use') {
+      const id = rest[0];
+      if (!id) return failure(runtime, 'invalid_persona_command', 'Usage: goodvibes-agent personas use <id>', 2);
+      const persona = registry.setActive(id);
+      return success(runtime, 'agent.personas.use', persona, [
+        'Active Agent persona',
+        `  id ${persona.id}`,
+      ].join('\n'));
+    }
+    if (normalized === 'clear') {
+      registry.clearActive();
+      return success(runtime, 'agent.personas.clear', { activePersonaId: null }, 'Active Agent persona cleared.');
+    }
+    if (normalized === 'review') {
+      const id = rest[0];
+      if (!id) return failure(runtime, 'invalid_persona_command', 'Usage: goodvibes-agent personas review <id>', 2);
+      const persona = registry.markReviewed(id);
+      return success(runtime, 'agent.personas.review', persona, [
+        'Agent persona reviewed',
+        `  id ${persona.id}`,
+      ].join('\n'));
+    }
+    if (normalized === 'stale') {
+      const id = rest[0];
+      if (!id || rest.length < 2) return failure(runtime, 'invalid_persona_command', 'Usage: goodvibes-agent personas stale <id> <reason>', 2);
+      const persona = registry.markStale(id, rest.slice(1).join(' '));
+      return success(runtime, 'agent.personas.stale', persona, [
+        'Agent persona marked stale',
+        `  id ${persona.id}`,
+      ].join('\n'));
+    }
+    if (normalized === 'delete' || normalized === 'remove' || normalized === 'rm') {
+      const options = parseOptions(rest);
+      const id = options.positionals[0];
+      if (!id) return failure(runtime, 'invalid_persona_command', 'Usage: goodvibes-agent personas delete <id> --yes', 2);
+      if (!hasFlag(options, 'yes')) return failure(runtime, 'confirmation_required', `Refusing to delete Agent persona ${id} without --yes.`, 2);
+      const persona = registry.deletePersona(id);
+      return success(runtime, 'agent.personas.delete', persona, [
+        `Agent persona deleted: ${id}`,
+        `  id ${persona.id}`,
+      ].join('\n'));
+    }
+    return failure(runtime, 'invalid_persona_command', usagePersonas(), 2);
+  } catch (error) {
+    return errorOutput(runtime, error, 'agent.personas.error');
+  }
+}

package/src/cli/resume-relaunch-notice.ts

@@ -0,0 +1,151 @@
+import type { SessionManager } from '@pellux/goodvibes-sdk/platform/sessions';
+
+/**
+ * RESUME-ON-RELAUNCH (W4-A4).
+ *
+ * The dogfood finding: relaunching the agent after a normal (non-crash) exit
+ * silently starts fresh with no offer or notice about the prior session — the
+ * only way back was knowing the exact `goodvibes-agent sessions resume <id>`
+ * command, or digging into `/health continuity`. This module builds an
+ * honest, one-line boot notice that surfaces the resume affordance without
+ * ever auto-resuming or blocking startup.
+ *
+ * Honesty rules (never claim restorability the app can't deliver):
+ *  - no last-session pointer on disk -> no notice (clean first run)
+ *  - a pointer exists but the session it names is missing/unreadable (stale
+ *    or dangling) -> say so plainly and point at `/session list`, never a
+ *    resume action that would dead-end
+ *  - a pointer exists and the session resolves -> an actionable one-liner
+ *    naming the EXISTING `/session resume <id>` path (this is surfacing, not
+ *    new resume logic)
+ *  - never auto-resume: the user always chooses, and declining is
+ *    frictionless (just start typing — the saved session stays put)
+ */
+
+/** Minimal session facts needed to render an honest resume notice. */
+export interface ResumableSessionSummary {
+  readonly sessionId: string;
+  readonly title: string;
+  readonly timestamp: number;
+  readonly messageCount: number;
+}
+
+export interface ResumeRelaunchNoticeInput {
+  /** The session id recorded in the last-session pointer file, or null when no pointer exists. */
+  readonly pointerSessionId: string | null;
+  /**
+   * The resolved session the pointer refers to, or null when the pointer
+   * exists but the session it names could not be found/read (stale or
+   * dangling pointer).
+   */
+  readonly session: ResumableSessionSummary | null;
+  readonly now?: number;
+}
+
+/**
+ * Formats an elapsed duration the way a human would describe "how long ago".
+ *
+ * F4 fix: this used Math.round at every tier, which rounds UP near a
+ * boundary — a session from 45 minutes ago (2,700,000ms) rounded to "1h ago"
+ * (round(45/60) = 1), which reads as roughly twice as stale as it really is.
+ * Every tier below now floors instead, so a duration is never described as
+ * further in the past than it actually is: 45m through 59m59s all read as
+ * "Nm ago", and the "1h" label only appears once a full hour has actually
+ * elapsed. Minutes are floored to at least 1 once past the 45s "moments"
+ * cutoff, so a duration just past that cutoff never reads as "0m ago".
+ */
+export function formatRelaunchAge(elapsedMs: number): string {
+  const elapsed = Math.max(0, elapsedMs);
+  const seconds = Math.floor(elapsed / 1000);
+  if (seconds < 45) return 'moments';
+  const minutes = Math.max(1, Math.floor(seconds / 60));
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 36) return `${hours}h`;
+  const days = Math.floor(hours / 24);
+  return `${days}d`;
+}
+
+/**
+ * Builds the boot-time resume notice text, or null when nothing should be
+ * shown (no pointer at all — a clean first run, or the caller already routed
+ * an explicit resume/onboarding command elsewhere).
+ */
+export function buildResumeRelaunchNotice(input: ResumeRelaunchNoticeInput): string | null {
+  if (!input.pointerSessionId) return null;
+
+  if (!input.session) {
+    return [
+      '[Resume] Your last session pointer is unavailable (the saved session may have been moved, renamed, or deleted).',
+      '  Starting fresh. Run /session list to see any sessions that are still on disk.',
+    ].join('\n');
+  }
+
+  // F5: a 0-message session has nothing to resume into — offering a resume
+  // action for it is a dead-end same as a stale pointer, but less honest,
+  // since the session itself does resolve. Stay silent, exactly like the
+  // no-pointer (clean first run) case above, rather than dangle a resume
+  // command in front of an empty conversation.
+  if (input.session.messageCount <= 0) return null;
+
+  const { session } = input;
+  const age = formatRelaunchAge((input.now ?? Date.now()) - session.timestamp);
+  const label = session.title.trim() || session.sessionId;
+  const messageWord = session.messageCount === 1 ? 'message' : 'messages';
+
+  return [
+    `[Resume] Your last session is available: "${label}" — ${age} ago, ${session.messageCount} ${messageWord}.`,
+    `  Resume it: /session resume ${session.sessionId}`,
+    '  Or just start typing to begin a new session — the saved one stays put.',
+  ].join('\n');
+}
+
+/**
+ * Resolves the pointer session id to its display facts via the existing
+ * SessionManager, honestly returning null when the session is missing or
+ * unreadable rather than throwing.
+ */
+export function resolveResumableSession(
+  sessionManager: Pick<SessionManager, 'list'>,
+  pointerSessionId: string,
+): ResumableSessionSummary | null {
+  const found = sessionManager.list().find((session) => session.name === pointerSessionId);
+  if (!found) return null;
+  return {
+    sessionId: found.name,
+    title: found.title,
+    timestamp: found.timestamp,
+    messageCount: found.messageCount,
+  };
+}
+
+export interface SurfaceResumeRelaunchNoticeDeps {
+  readonly getLastSessionPointer: () => string | null;
+  /** True when a crash-recovery prompt is already showing (that flow owns its own restore path and takes priority). */
+  readonly isRecoveryPending: () => boolean;
+  readonly findSession: (sessionId: string) => ResumableSessionSummary | null;
+  readonly print: (text: string) => void;
+  readonly now?: () => number;
+}
+
+/**
+ * Decides whether to surface the resume notice and prints it. Never throws,
+ * never blocks startup, and never auto-resumes — the user always chooses by
+ * running the printed command or by just typing to start fresh.
+ */
+export function surfaceResumeRelaunchNotice(deps: SurfaceResumeRelaunchNoticeDeps): void {
+  try {
+    if (deps.isRecoveryPending()) return;
+    const pointerSessionId = deps.getLastSessionPointer();
+    if (!pointerSessionId) return;
+    const session = deps.findSession(pointerSessionId);
+    const notice = buildResumeRelaunchNotice({
+      pointerSessionId,
+      session,
+      now: deps.now ? deps.now() : Date.now(),
+    });
+    if (notice) deps.print(notice);
+  } catch {
+    // Never block startup on a resume-notice failure.
+  }
+}

package/src/cli/routines-command.ts

@@ -290,7 +290,7 @@ async function handleRoutinePromotion(runtime: CliCommandRuntime, args: readonly
   if (!parsed.yes) {
     const value: RoutinesCommandSuccess<typeof preview> = {
       ok: true,
-      kind: 'schedules.create.preview',
+      kind: 'automation.schedules.create.preview',
       data: preview,
     };
     return {
@@ -496,6 +496,29 @@ export async function handleRoutinesCommand(runtime: CliCommandRuntime): Promise
       exitCode: 0,
     };
   }
+  if (normalized === 'delete' || normalized === 'remove') {
+    const options = parseRoutineOptions(rest);
+    const id = options.positionals[0];
+    if (!id) return { output: 'Usage: goodvibes-agent routines delete <id> --yes', exitCode: 2 };
+    if (!options.yes) {
+      return { output: `Refusing to delete Agent routine ${id} without --yes.`, exitCode: 2 };
+    }
+    try {
+      const routine = registry.deleteRoutine(id);
+      const value: RoutinesCommandSuccess<AgentRoutineRecord> = { ok: true, kind: 'agent.routines.delete', data: routine };
+      return {
+        output: jsonOrText(runtime, value, `Deleted Agent routine ${routine.id}: ${routine.name}`),
+        exitCode: 0,
+      };
+    } catch (error) {
+      return commandFailure(
+        runtime,
+        'routine_not_found',
+        error instanceof Error ? error.message : String(error),
+        1,
+      );
+    }
+  }
   if (normalized === 'receipts' || normalized === 'history') {
     const snapshot = routineReceiptStore(runtime).snapshot();
     const value: RoutinesCommandSuccess<typeof snapshot> = {
@@ -544,7 +567,7 @@ export async function handleRoutinesCommand(runtime: CliCommandRuntime): Promise
     return handleRoutinePromotion(runtime, rest);
   }
   return {
-    output: `Usage: goodvibes-agent routines [list|enabled|attention|discover|import-discovered <name> --yes|create --name <name> --description <summary> --steps <steps>|show <id>|receipts|reconcile|receipt <id>|promote <id> (--cron <expr>|--every <interval>|--at <iso-time>) [--delivery-channel <channel>|--delivery-route <route>|--delivery-webhook <url>] --yes]`,
+    output: `Usage: goodvibes-agent routines [list|enabled|attention|discover|import-discovered <name> --yes|create --name <name> --description <summary> --steps <steps>|show <id>|delete <id> --yes|receipts|reconcile|receipt <id>|promote <id> (--cron <expr>|--every <interval>|--at <iso-time>) [--delivery-channel <channel>|--delivery-route <route>|--delivery-webhook <url>] --yes]`,
     exitCode: 2,
   };
 }

package/src/cli/service-posture.ts

@@ -1,6 +1,7 @@
 import { closeSync, existsSync, openSync, readSync, statSync } from 'node:fs';
 import net from 'node:net';
 import { isAbsolute, join } from 'node:path';
+import { resolveDaemonEnabled } from '@pellux/goodvibes-sdk/platform/config';
 import type { ConfigKey, ConfigManager } from '../config/index.ts';
 import { resolveRuntimeEndpointBinding } from './endpoints.ts';
 import type { RuntimeEndpointBinding, RuntimeEndpointId } from './endpoints.ts';
@@ -178,7 +179,7 @@ export async function buildCliServicePosture(
     enabled: runtime.configManager.get('service.enabled') === true,
     autostart: runtime.configManager.get('service.autostart') === true,
     restartOnFailure: runtime.configManager.get('service.restartOnFailure') === true,
-    daemonEnabled: runtime.configManager.get('danger.daemon') === true,
+    daemonEnabled: resolveDaemonEnabled(runtime.configManager),
   };
   const serverBackedEnabled = config.daemonEnabled || endpoints.some((endpoint) => endpoint.enabled);
   const issues: string[] = [];
@@ -228,7 +229,7 @@ export function formatCliServicePosture(posture: CliServicePosture, json = false
     '  Agent starts connected host: no',
     `  external host config present: ${yesNo(posture.config.enabled)}`,
     '  external host lifecycle config: ignored by Agent',
-    `  legacy host switch present: ${yesNo(posture.config.daemonEnabled)}`,
+    `  daemon considered enabled: ${yesNo(posture.config.daemonEnabled)}`,
     `  log: ${posture.log.path ?? 'n/a'} (${posture.log.exists ? 'present' : 'missing'})`,
     ...(posture.log.readError ? [`  log read error: ${posture.log.readError}`] : []),
     '',

package/src/cli/skill-bundle-command.ts

@@ -0,0 +1,175 @@
+import { formatAgentRecordOrigin, formatAgentRecordReviewState } from '../agent/record-labels.ts';
+import {
+  evaluateAgentSkillBundleReadiness,
+  formatAgentSkillRequirement,
+  type AgentSkillBundleRecord,
+  type AgentSkillRecord,
+} from '../agent/skill-registry.ts';
+import type { CliCommandOutput } from './types.ts';
+import type { CliCommandRuntime } from './management.ts';
+import {
+  csvOption,
+  errorOutput,
+  failure,
+  hasFlag,
+  optionValue,
+  parseOptions,
+  requiredOption,
+  skillRegistry,
+  success,
+} from './local-library-command-shared.ts';
+
+function summarizeBundle(bundle: AgentSkillBundleRecord, skills: readonly AgentSkillRecord[]): string {
+  const enabled = bundle.enabled ? 'enabled' : 'disabled';
+  const readiness = evaluateAgentSkillBundleReadiness(bundle, skills);
+  const missing = [
+    ...readiness.missingRequirements.map(formatAgentSkillRequirement),
+    ...readiness.missingSkillIds.map((skillId) => `skill:${skillId}`),
+  ];
+  const ready = readiness.ready ? 'ready' : `needs ${missing.join(',')}`;
+  return `  ${bundle.id}  ${enabled}  ${formatAgentRecordReviewState(bundle.reviewState)}  ${ready}  ${bundle.name} - ${bundle.description} skills ${bundle.skillIds.join(',')}`;
+}
+
+export function renderBundleList(title: string, path: string, bundles: readonly AgentSkillBundleRecord[], skills: readonly AgentSkillRecord[], emptyMessage?: string): string {
+  if (bundles.length === 0) {
+    return [
+      title,
+      `  ${emptyMessage ?? 'No Agent-local skill bundles yet.'}`,
+      emptyMessage ? '' : '  Create one with: goodvibes-agent skills bundle create --name <name> --description <summary> --skills <id,id>',
+    ].filter(Boolean).join('\n');
+  }
+  return [
+    `${title} (${bundles.length})`,
+    `  store ${path}`,
+    ...bundles.map((bundle) => summarizeBundle(bundle, skills)),
+  ].join('\n');
+}
+
+function renderBundle(bundle: AgentSkillBundleRecord, skills: readonly AgentSkillRecord[]): string {
+  const readiness = evaluateAgentSkillBundleReadiness(bundle, skills);
+  const missing = [
+    ...readiness.missingRequirements.map(formatAgentSkillRequirement),
+    ...readiness.missingSkillIds.map((skillId) => `skill:${skillId}`),
+  ];
+  return [
+    `Skill bundle ${bundle.name}`,
+    `  id ${bundle.id}`,
+    `  enabled: ${bundle.enabled ? 'yes' : 'no'}`,
+    `  readiness: ${readiness.ready ? 'ready' : 'needs setup'}`,
+    missing.length > 0 ? `  missing: ${missing.join(', ')}` : '',
+    `  review: ${formatAgentRecordReviewState(bundle.reviewState)}`,
+    `  origin: ${formatAgentRecordOrigin(bundle.source, bundle.provenance)}`,
+    `  skills: ${bundle.skillIds.join(', ')}`,
+    `  created: ${bundle.createdAt}`,
+    `  updated: ${bundle.updatedAt}`,
+    bundle.staleReason ? `  stale reason: ${bundle.staleReason}` : '',
+    '',
+    bundle.description,
+  ].filter((line): line is string => Boolean(line)).join('\n');
+}
+
+function usageBundles(): string {
+  return 'Usage: goodvibes-agent skills bundle [list|enabled|attention|search <query>|show <id>|create|update <id>|enable <id>|disable <id>|review <id>|stale <id> <reason>|delete <id> --yes]';
+}
+
+export async function handleSkillBundleCommand(runtime: CliCommandRuntime, args: readonly string[]): Promise<CliCommandOutput> {
+  try {
+    const [sub = 'list', ...rest] = args;
+    const normalized = sub.toLowerCase();
+    const registry = skillRegistry(runtime);
+    const snapshot = registry.snapshot();
+    if (normalized === 'list' || normalized === 'ls') {
+      return success(runtime, 'agent.skills.bundles.list', { path: snapshot.path, bundles: snapshot.bundles }, renderBundleList('Agent skill bundles', snapshot.path, snapshot.bundles, snapshot.skills));
+    }
+    if (normalized === 'enabled') {
+      return success(runtime, 'agent.skills.bundles.enabled', { path: snapshot.path, bundles: snapshot.enabledBundles }, renderBundleList('Enabled Agent skill bundles', snapshot.path, snapshot.enabledBundles, snapshot.skills));
+    }
+    if (normalized === 'attention' || normalized === 'needs-setup') {
+      const bundles = snapshot.bundles.filter((bundle) => !evaluateAgentSkillBundleReadiness(bundle, snapshot.skills).ready);
+      return success(runtime, 'agent.skills.bundles.attention', { path: snapshot.path, bundles }, renderBundleList('Agent skill bundles needing setup', snapshot.path, bundles, snapshot.skills, 'No Agent-local skill bundles need setup.'));
+    }
+    if (normalized === 'search' || normalized === 'find') {
+      const query = rest.join(' ').trim();
+      const results = registry.searchBundles(query);
+      return success(runtime, 'agent.skills.bundles.search', { query, results }, renderBundleList(`Agent skill bundles matching "${query}"`, snapshot.path, results, snapshot.skills));
+    }
+    if (normalized === 'show' || normalized === 'get') {
+      const id = rest[0];
+      if (!id) return failure(runtime, 'invalid_skill_bundle_command', 'Usage: goodvibes-agent skills bundle show <id>', 2);
+      const bundle = registry.getBundle(id);
+      if (!bundle) return failure(runtime, 'skill_bundle_not_found', `Unknown Agent skill bundle ${id}`, 1);
+      return success(runtime, 'agent.skills.bundles.show', bundle, renderBundle(bundle, snapshot.skills));
+    }
+    if (normalized === 'create') {
+      const options = parseOptions(rest);
+      const usage = 'Usage: goodvibes-agent skills bundle create --name <name> --description <summary> --skills <id,id>';
+      const bundle = registry.createBundle({
+        name: requiredOption(options, 'name', usage),
+        description: requiredOption(options, 'description', usage),
+        skillIds: requiredOption(options, 'skills', usage).split(',').map((entry) => entry.trim()).filter(Boolean),
+        enabled: hasFlag(options, 'enabled'),
+        provenance: optionValue(options, 'provenance') ?? 'Command',
+      });
+      return success(runtime, 'agent.skills.bundles.create', bundle, [
+        'Agent skill bundle created',
+        `  id ${bundle.id}`,
+      ].join('\n'));
+    }
+    if (normalized === 'update') {
+      const id = rest[0];
+      if (!id) return failure(runtime, 'invalid_skill_bundle_command', 'Usage: goodvibes-agent skills bundle update <id> [--name ...] [--description ...] [--skills id,id]', 2);
+      const options = parseOptions(rest.slice(1));
+      const bundle = registry.updateBundle(id, {
+        name: optionValue(options, 'name'),
+        description: optionValue(options, 'description'),
+        skillIds: csvOption(options, 'skills'),
+        provenance: optionValue(options, 'provenance'),
+      });
+      return success(runtime, 'agent.skills.bundles.update', bundle, [
+        'Agent skill bundle updated',
+        `  id ${bundle.id}`,
+      ].join('\n'));
+    }
+    if (normalized === 'enable' || normalized === 'disable') {
+      const id = rest[0];
+      if (!id) return failure(runtime, 'invalid_skill_bundle_command', `Usage: goodvibes-agent skills bundle ${normalized} <id>`, 2);
+      const bundle = registry.setBundleEnabled(id, normalized === 'enable');
+      return success(runtime, `agent.skills.bundles.${normalized}`, bundle, [
+        `Agent skill bundle ${normalized === 'enable' ? 'enabled' : 'disabled'}`,
+        `  id ${bundle.id}`,
+      ].join('\n'));
+    }
+    if (normalized === 'review') {
+      const id = rest[0];
+      if (!id) return failure(runtime, 'invalid_skill_bundle_command', 'Usage: goodvibes-agent skills bundle review <id>', 2);
+      const bundle = registry.markBundleReviewed(id);
+      return success(runtime, 'agent.skills.bundles.review', bundle, [
+        'Agent skill bundle reviewed',
+        `  id ${bundle.id}`,
+      ].join('\n'));
+    }
+    if (normalized === 'stale') {
+      const id = rest[0];
+      if (!id || rest.length < 2) return failure(runtime, 'invalid_skill_bundle_command', 'Usage: goodvibes-agent skills bundle stale <id> <reason>', 2);
+      const bundle = registry.markBundleStale(id, rest.slice(1).join(' '));
+      return success(runtime, 'agent.skills.bundles.stale', bundle, [
+        'Agent skill bundle marked stale',
+        `  id ${bundle.id}`,
+      ].join('\n'));
+    }
+    if (normalized === 'delete' || normalized === 'remove' || normalized === 'rm') {
+      const options = parseOptions(rest);
+      const id = options.positionals[0];
+      if (!id) return failure(runtime, 'invalid_skill_bundle_command', 'Usage: goodvibes-agent skills bundle delete <id> --yes', 2);
+      if (!hasFlag(options, 'yes')) return failure(runtime, 'confirmation_required', `Refusing to delete Agent skill bundle ${id} without --yes.`, 2);
+      const bundle = registry.deleteBundle(id);
+      return success(runtime, 'agent.skills.bundles.delete', bundle, [
+        'Agent skill bundle deleted',
+        `  id ${bundle.id}`,
+      ].join('\n'));
+    }
+    return failure(runtime, 'invalid_skill_bundle_command', usageBundles(), 2);
+  } catch (error) {
+    return errorOutput(runtime, error, 'agent.skills.bundles.error');
+  }
+}