@pellux/goodvibes-agent 0.1.116 → 1.0.0

package/src/input/commands/agent-skills-runtime.ts

@@ -1,5 +1,14 @@
-import { AgentSkillRegistry, type AgentSkillBundleRecord, type AgentSkillRecord } from '../../agent/skill-registry.ts';
+import {
+  AgentSkillRegistry,
+  buildAgentSkillRequirements,
+  evaluateAgentSkillBundleReadiness,
+  evaluateAgentSkillReadiness,
+  formatAgentSkillRequirement,
+  type AgentSkillBundleRecord,
+  type AgentSkillRecord,
+} from '../../agent/skill-registry.ts';
 import { discoverSkills, type SkillRecord } from '../../agent/skill-discovery.ts';
+import { formatAgentRecordOrigin, formatAgentRecordReviewState } from '../../agent/record-labels.ts';
 import type { CommandContext, CommandRegistry } from '../command-registry.ts';
 import { requireShellPaths } from './runtime-services.ts';
 
@@ -50,35 +59,56 @@ function requiredFlag(flags: ReadonlyMap<string, string>, key: string): string {
   return value;
 }
 
+function formatSkillReceipt(title: string, record: { readonly id: string; readonly name: string }, extra: readonly string[] = []): string {
+  return [
+    `${title} ${record.id}`,
+    `  id ${record.id}`,
+    `  name ${record.name}`,
+    ...extra,
+  ].join('\n');
+}
+
 function summarizeSkill(skill: AgentSkillRecord): string {
   const enabled = skill.enabled ? 'enabled' : 'disabled';
-  const tags = skill.tags.length > 0 ? ` tags=${skill.tags.join(',')}` : '';
-  return `  ${skill.id}  ${enabled}  ${skill.reviewState}  ${skill.name} - ${skill.description}${tags}`;
+  const tags = skill.tags.length > 0 ? ` tags ${skill.tags.join(', ')}` : '';
+  const readiness = evaluateAgentSkillReadiness(skill);
+  const review = formatAgentRecordReviewState(skill.reviewState);
+  const ready = readiness.ready ? 'ready' : `needs ${readiness.missing.map(formatAgentSkillRequirement).join(',')}`;
+  return `  ${skill.id}  ${enabled}  ${review}  ${ready}  ${skill.name} - ${skill.description}${tags}`;
 }
 
-function summarizeBundle(bundle: AgentSkillBundleRecord): string {
+function summarizeBundle(bundle: AgentSkillBundleRecord, skills: readonly AgentSkillRecord[]): string {
   const enabled = bundle.enabled ? 'enabled' : 'disabled';
-  return `  ${bundle.id}  ${enabled}  ${bundle.reviewState}  ${bundle.name} - ${bundle.description}  skills=${bundle.skillIds.join(',')}`;
+  const readiness = evaluateAgentSkillBundleReadiness(bundle, skills);
+  const review = formatAgentRecordReviewState(bundle.reviewState);
+  const missing = [
+    ...readiness.missingRequirements.map(formatAgentSkillRequirement),
+    ...readiness.missingSkillIds.map((skillId) => `skill ${skillId}`),
+  ];
+  const ready = readiness.ready ? 'ready' : `needs ${missing.join(',')}`;
+  return `  ${bundle.id}  ${enabled}  ${review}  ${ready}  ${bundle.name} - ${bundle.description}  skills ${bundle.skillIds.join(', ')}`;
 }
 
-function renderList(title: string, registry: AgentSkillRegistry, skills: readonly AgentSkillRecord[]): string {
+function renderList(title: string, registry: AgentSkillRegistry, skills: readonly AgentSkillRecord[], emptyMessage?: string): string {
   const snapshot = registry.snapshot();
   if (skills.length === 0) {
-    return `${title}\n  No local Agent skills yet. Create one with /agent-skills create --name <name> --description <summary> --procedure <steps>.`;
+    return emptyMessage
+      ? `${title}\n  ${emptyMessage}`
+      : `${title}\n  No Agent-local skills yet. Create one with /skills create --name <name> --description <summary> --procedure <steps>.`;
   }
   return [
     `${title} (${skills.length})`,
-    `  store: ${snapshot.path}`,
-    `  enabled: ${snapshot.enabledSkills.length}`,
+    `  store ${snapshot.path}`,
+    `  enabled ${snapshot.enabledSkills.length}`,
     ...skills.map(summarizeSkill),
   ].join('\n');
 }
 
 function summarizeDiscoveredSkill(skill: SkillRecord): string {
   const description = skill.description ? ` - ${skill.description}` : '';
-  const dependencies = skill.dependencies.length > 0 ? ` deps=${skill.dependencies.join(',')}` : '';
-  const includes = skill.includes.length > 0 ? ` includes=${skill.includes.join(',')}` : '';
-  return `  ${skill.name}  ${skill.origin}${description}${dependencies}${includes}\n    path: ${skill.path}`;
+  const dependencies = skill.dependencies.length > 0 ? ` deps ${skill.dependencies.join(', ')}` : '';
+  const includes = skill.includes.length > 0 ? ` includes ${skill.includes.join(', ')}` : '';
+  return `  ${skill.name}  ${skill.origin}${description}${dependencies}${includes}\n    path ${skill.path}`;
 }
 
 function renderDiscoveredSkills(skills: readonly SkillRecord[]): string {
@@ -93,7 +123,7 @@ function renderDiscoveredSkills(skills: readonly SkillRecord[]): string {
     `Discovered Agent skill files (${skills.length})`,
     ...skills.map(summarizeDiscoveredSkill),
     '',
-    'Import one with: /agent-skills import-discovered <name> --yes',
+    'Import one with: /skills import-discovered <name> --yes',
   ].join('\n');
 }
 
@@ -120,27 +150,35 @@ function frontmatterList(skill: SkillRecord, key: string): readonly string[] {
   return splitList(value);
 }
 
+function frontmatterAnyList(skill: SkillRecord, keys: readonly string[]): readonly string[] {
+  for (const key of keys) {
+    const values = frontmatterList(skill, key);
+    if (values.length > 0) return values;
+  }
+  return [];
+}
+
 async function importDiscoveredSkill(args: readonly string[], ctx: CommandContext, skillRegistry: AgentSkillRegistry): Promise<void> {
   const parsed = parseSkillArgs(args);
   const name = parsed.rest.join(' ').trim();
   if (!name) {
-    ctx.print('Usage: /agent-skills import-discovered <name> [--enabled] --yes');
+    ctx.print('Usage: /skills import-discovered <name> [--enabled] --yes');
     return;
   }
   const discovered = findDiscoveredSkill(await discoverSkills(requireShellPaths(ctx)), name);
   if (!discovered) {
-    ctx.print(`Unknown discovered Agent skill: ${name}\nRun /agent-skills discover to inspect available skill files.`);
+    ctx.print(`Unknown discovered Agent skill ${name}\nRun /skills discover to inspect available skill files.`);
     return;
   }
   if (!parsed.yes) {
     ctx.print([
       'Agent skill import preview',
-      `  name: ${discovered.name}`,
-      `  origin: ${discovered.origin}`,
-      `  path: ${discovered.path}`,
-      `  description: ${discovered.description || '(none)'}`,
-      `  procedure characters: ${discovered.body.length}`,
-      '  next: rerun with --yes to import into the Agent-local skill registry',
+      `  name ${discovered.name}`,
+      `  origin ${discovered.origin}`,
+      `  path ${discovered.path}`,
+      `  description ${discovered.description || '(none)'}`,
+      `  procedure characters ${discovered.body.length}`,
+      '  next rerun with --yes to import into the Agent-local skill registry',
     ].join('\n'));
     return;
   }
@@ -150,35 +188,44 @@ async function importDiscoveredSkill(args: readonly string[], ctx: CommandContex
     procedure: discovered.body,
     triggers: frontmatterList(discovered, 'triggers'),
     tags: frontmatterList(discovered, 'tags'),
+    requirements: buildAgentSkillRequirements({
+      env: frontmatterAnyList(discovered, ['requiresEnv', 'requires-env', 'requires_env']),
+      commands: frontmatterAnyList(discovered, ['requiresCommands', 'requires-commands', 'requires_commands', 'commands']),
+    }),
     enabled: parsed.flags.get('enabled') === 'true',
     source: 'imported',
-    provenance: `discovered:${discovered.origin}:${discovered.path}`,
+    provenance: `Imported file (${discovered.origin}): ${discovered.path}`,
   });
-  ctx.print(`Imported Agent skill ${skill.id}: ${skill.name}`);
+  ctx.print(formatSkillReceipt('Imported Agent skill', skill, [`  enabled ${skill.enabled ? 'yes' : 'no'}`]));
 }
 
-function renderBundleList(title: string, registry: AgentSkillRegistry, bundles: readonly AgentSkillBundleRecord[]): string {
+function renderBundleList(title: string, registry: AgentSkillRegistry, bundles: readonly AgentSkillBundleRecord[], emptyMessage?: string): string {
   const snapshot = registry.snapshot();
   if (bundles.length === 0) {
-    return `${title}\n  No local Agent skill bundles yet. Create one with /agent-skills bundle create --name <name> --description <summary> --skills <id,id>.`;
+    return emptyMessage
+      ? `${title}\n  ${emptyMessage}`
+      : `${title}\n  No Agent-local skill bundles yet. Create one with /skills bundle create --name <name> --description <summary> --skills <id,id>.`;
   }
   return [
     `${title} (${bundles.length})`,
-    `  store: ${snapshot.path}`,
+    `  store ${snapshot.path}`,
     `  enabled bundles: ${snapshot.enabledBundles.length}`,
     `  active skills: ${snapshot.activeSkills.length}`,
-    ...bundles.map(summarizeBundle),
+    ...bundles.map((bundle) => summarizeBundle(bundle, snapshot.skills)),
   ].join('\n');
 }
 
 function renderSkill(skill: AgentSkillRecord): string {
+  const readiness = evaluateAgentSkillReadiness(skill);
   return [
     `Skill ${skill.name}`,
-    `  id: ${skill.id}`,
+    `  id ${skill.id}`,
     `  enabled: ${skill.enabled ? 'yes' : 'no'}`,
-    `  review: ${skill.reviewState}`,
-    `  source: ${skill.source}`,
-    `  provenance: ${skill.provenance}`,
+    `  readiness: ${readiness.ready ? 'ready' : 'needs setup'}`,
+    `  requirements: ${skill.requirements.map(formatAgentSkillRequirement).join(', ') || '(none)'}`,
+    readiness.missing.length > 0 ? `  missing: ${readiness.missing.map(formatAgentSkillRequirement).join(', ')}` : '',
+    `  review: ${formatAgentRecordReviewState(skill.reviewState)}`,
+    `  origin: ${formatAgentRecordOrigin(skill.source, skill.provenance)}`,
     `  tags: ${skill.tags.join(', ') || '(none)'}`,
     `  triggers: ${skill.triggers.join(', ') || '(manual)'}`,
     `  created: ${skill.createdAt}`,
@@ -195,13 +242,19 @@ function renderBundle(bundle: AgentSkillBundleRecord, registry: AgentSkillRegist
   const skills = bundle.skillIds
     .map((skillId) => registry.get(skillId))
     .filter((skill): skill is AgentSkillRecord => skill !== null);
+  const readiness = evaluateAgentSkillBundleReadiness(bundle, registry.snapshot().skills);
+  const missing = [
+    ...readiness.missingRequirements.map(formatAgentSkillRequirement),
+    ...readiness.missingSkillIds.map((skillId) => `skill ${skillId}`),
+  ];
   return [
     `Skill Bundle ${bundle.name}`,
-    `  id: ${bundle.id}`,
+    `  id ${bundle.id}`,
     `  enabled: ${bundle.enabled ? 'yes' : 'no'}`,
-    `  review: ${bundle.reviewState}`,
-    `  source: ${bundle.source}`,
-    `  provenance: ${bundle.provenance}`,
+    `  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}`,
@@ -214,7 +267,10 @@ function renderBundle(bundle: AgentSkillBundleRecord, registry: AgentSkillRegist
 }
 
 function printError(ctx: CommandContext, error: unknown): void {
-  ctx.print(`Error: ${error instanceof Error ? error.message : String(error)}`);
+  ctx.print([
+    'Error',
+    `  message ${error instanceof Error ? error.message : String(error)}`,
+  ].join('\n'));
 }
 
 function runBundleCommand(args: readonly string[], ctx: CommandContext, skillRegistry: AgentSkillRegistry): void {
@@ -228,6 +284,12 @@ function runBundleCommand(args: readonly string[], ctx: CommandContext, skillReg
     ctx.print(renderBundleList('Enabled Agent Skill Bundles', skillRegistry, snapshot.enabledBundles));
     return;
   }
+  if (sub === 'attention' || sub === 'needs-setup') {
+    const snapshot = skillRegistry.snapshot();
+    const bundles = snapshot.bundles.filter((bundle) => !evaluateAgentSkillBundleReadiness(bundle, snapshot.skills).ready);
+    ctx.print(renderBundleList('Agent Skill Bundles needing setup', skillRegistry, bundles, 'No Agent-local skill bundles need setup.'));
+    return;
+  }
   if (sub === 'search') {
     const query = args.slice(1).join(' ').trim();
     ctx.print(renderBundleList(query ? `Agent Skill Bundles matching "${query}"` : 'Agent Skill Bundles', skillRegistry, skillRegistry.searchBundles(query)));
@@ -236,11 +298,11 @@ function runBundleCommand(args: readonly string[], ctx: CommandContext, skillReg
   if (sub === 'show') {
     const id = args[1];
     if (!id) {
-      ctx.print('Usage: /agent-skills bundle show <id>');
+      ctx.print('Usage: /skills bundle show <id>');
       return;
     }
     const bundle = skillRegistry.getBundle(id);
-    ctx.print(bundle ? renderBundle(bundle, skillRegistry) : `Unknown Agent skill bundle: ${id}`);
+    ctx.print(bundle ? renderBundle(bundle, skillRegistry) : `Unknown Agent skill bundle ${id}`);
     return;
   }
   if (sub === 'create') {
@@ -251,15 +313,15 @@ function runBundleCommand(args: readonly string[], ctx: CommandContext, skillReg
       skillIds: splitList(requiredFlag(parsed.flags, 'skills')),
       enabled: parsed.flags.get('enabled') === 'true',
       source: 'user',
-      provenance: 'slash-command',
+      provenance: 'Command',
     });
-    ctx.print(`Created Agent skill bundle ${bundle.id}: ${bundle.name}`);
+    ctx.print(formatSkillReceipt('Created Agent skill bundle', bundle));
     return;
   }
   if (sub === 'update') {
     const id = args[1];
     if (!id) {
-      ctx.print('Usage: /agent-skills bundle update <id> [--name ...] [--description ...] [--skills id,id]');
+      ctx.print('Usage: /skills bundle update <id> [--name ...] [--description ...] [--skills id,id]');
       return;
     }
     const parsed = parseSkillArgs(args.slice(2));
@@ -267,46 +329,46 @@ function runBundleCommand(args: readonly string[], ctx: CommandContext, skillReg
       name: parsed.flags.get('name'),
       description: parsed.flags.get('description'),
       skillIds: parsed.flags.has('skills') ? splitList(parsed.flags.get('skills')) : undefined,
-      provenance: 'slash-command',
+      provenance: 'Command',
     });
-    ctx.print(`Updated Agent skill bundle ${updated.id}: ${updated.name}`);
+    ctx.print(formatSkillReceipt('Updated Agent skill bundle', updated));
     return;
   }
   if (sub === 'enable' || sub === 'disable') {
     const id = args[1];
     if (!id) {
-      ctx.print(`Usage: /agent-skills bundle ${sub} <id>`);
+      ctx.print(`Usage: /skills bundle ${sub} <id>`);
       return;
     }
     const bundle = skillRegistry.setBundleEnabled(id, sub === 'enable');
-    ctx.print(`${sub === 'enable' ? 'Enabled' : 'Disabled'} Agent skill bundle ${bundle.id}: ${bundle.name}`);
+    ctx.print(formatSkillReceipt(`${sub === 'enable' ? 'Enabled' : 'Disabled'} Agent skill bundle`, bundle));
     return;
   }
   if (sub === 'review') {
     const id = args[1];
     if (!id) {
-      ctx.print('Usage: /agent-skills bundle review <id>');
+      ctx.print('Usage: /skills bundle review <id>');
       return;
     }
     const bundle = skillRegistry.markBundleReviewed(id);
-    ctx.print(`Reviewed Agent skill bundle ${bundle.id}.`);
+    ctx.print(formatSkillReceipt('Reviewed Agent skill bundle', bundle));
     return;
   }
   if (sub === 'stale') {
     const id = args[1];
     if (!id) {
-      ctx.print('Usage: /agent-skills bundle stale <id> <reason...>');
+      ctx.print('Usage: /skills bundle stale <id> <reason...>');
       return;
     }
     const bundle = skillRegistry.markBundleStale(id, args.slice(2).join(' '));
-    ctx.print(`Marked Agent skill bundle ${bundle.id} stale.`);
+    ctx.print(formatSkillReceipt('Marked Agent skill bundle stale', bundle));
     return;
   }
   if (sub === 'delete' || sub === 'remove') {
     const parsed = parseSkillArgs(args.slice(1));
     const id = parsed.rest[0];
     if (!id) {
-      ctx.print('Usage: /agent-skills bundle delete <id> --yes');
+      ctx.print('Usage: /skills bundle delete <id> --yes');
       return;
     }
     if (!parsed.yes) {
@@ -314,10 +376,10 @@ function runBundleCommand(args: readonly string[], ctx: CommandContext, skillReg
       return;
     }
     const removed = skillRegistry.deleteBundle(id);
-    ctx.print(`Deleted Agent skill bundle ${removed.id}: ${removed.name}`);
+    ctx.print(formatSkillReceipt('Deleted Agent skill bundle', removed));
     return;
   }
-  ctx.print('Usage: /agent-skills bundle [list|enabled|search|show|create|update|enable|disable|review|stale|delete]');
+  ctx.print('Usage: /skills bundle [list|enabled|attention|search|show|create|update|enable|disable|review|stale|delete]');
 }
 
 export async function runAgentSkillsRuntimeCommand(args: readonly string[], ctx: CommandContext): Promise<void> {
@@ -349,6 +411,11 @@ export async function runAgentSkillsRuntimeCommand(args: readonly string[], ctx:
       ctx.print(renderList('Enabled Agent Skills', skillRegistry, snapshot.enabledSkills));
       return;
     }
+    if (sub === 'attention' || sub === 'needs-setup') {
+      const skills = skillRegistry.list().filter((skill) => !evaluateAgentSkillReadiness(skill).ready);
+      ctx.print(renderList('Agent Skills needing setup', skillRegistry, skills, 'No Agent-local skills need setup.'));
+      return;
+    }
     if (sub === 'search') {
       const query = args.slice(1).join(' ').trim();
       ctx.print(renderList(query ? `Agent Skills matching "${query}"` : 'Agent Skills', skillRegistry, skillRegistry.search(query)));
@@ -357,11 +424,11 @@ export async function runAgentSkillsRuntimeCommand(args: readonly string[], ctx:
     if (sub === 'show') {
       const id = args[1];
       if (!id) {
-        ctx.print('Usage: /agent-skills show <id>');
+        ctx.print('Usage: /skills show <id>');
         return;
       }
       const skill = skillRegistry.get(id);
-      ctx.print(skill ? renderSkill(skill) : `Unknown Agent skill: ${id}`);
+      ctx.print(skill ? renderSkill(skill) : `Unknown Agent skill ${id}`);
       return;
     }
     if (sub === 'create') {
@@ -373,17 +440,21 @@ export async function runAgentSkillsRuntimeCommand(args: readonly string[], ctx:
         procedure,
         triggers: splitList(parsed.flags.get('triggers')),
         tags: splitList(parsed.flags.get('tags')),
+        requirements: buildAgentSkillRequirements({
+          env: splitList(parsed.flags.get('requires-env')),
+          commands: splitList(parsed.flags.get('requires-command') ?? parsed.flags.get('requires-commands')),
+        }),
         enabled: parsed.flags.get('enabled') === 'true',
         source: 'user',
-        provenance: 'slash-command',
+        provenance: 'Command',
       });
-      ctx.print(`Created Agent skill ${skill.id}: ${skill.name}`);
+      ctx.print(formatSkillReceipt('Created Agent skill', skill));
       return;
     }
     if (sub === 'update') {
       const id = args[1];
       if (!id) {
-        ctx.print('Usage: /agent-skills update <id> [--name ...] [--description ...] [--procedure ...]');
+        ctx.print('Usage: /skills update <id> [--name ...] [--description ...] [--procedure ...]');
         return;
       }
       const parsed = parseSkillArgs(args.slice(2));
@@ -393,46 +464,52 @@ export async function runAgentSkillsRuntimeCommand(args: readonly string[], ctx:
         procedure: parsed.flags.get('procedure'),
         triggers: parsed.flags.has('triggers') ? splitList(parsed.flags.get('triggers')) : undefined,
         tags: parsed.flags.has('tags') ? splitList(parsed.flags.get('tags')) : undefined,
-        provenance: 'slash-command',
+        requirements: parsed.flags.has('requires-env') || parsed.flags.has('requires-command') || parsed.flags.has('requires-commands')
+          ? buildAgentSkillRequirements({
+            env: splitList(parsed.flags.get('requires-env')),
+            commands: splitList(parsed.flags.get('requires-command') ?? parsed.flags.get('requires-commands')),
+          })
+          : undefined,
+        provenance: 'Command',
       });
-      ctx.print(`Updated Agent skill ${updated.id}: ${updated.name}`);
+      ctx.print(formatSkillReceipt('Updated Agent skill', updated));
       return;
     }
     if (sub === 'enable' || sub === 'disable') {
       const id = args[1];
       if (!id) {
-        ctx.print(`Usage: /agent-skills ${sub} <id>`);
+        ctx.print(`Usage: /skills ${sub} <id>`);
         return;
       }
       const skill = skillRegistry.setEnabled(id, sub === 'enable');
-      ctx.print(`${sub === 'enable' ? 'Enabled' : 'Disabled'} Agent skill ${skill.id}: ${skill.name}`);
+      ctx.print(formatSkillReceipt(`${sub === 'enable' ? 'Enabled' : 'Disabled'} Agent skill`, skill));
       return;
     }
     if (sub === 'review') {
       const id = args[1];
       if (!id) {
-        ctx.print('Usage: /agent-skills review <id>');
+        ctx.print('Usage: /skills review <id>');
         return;
       }
       const skill = skillRegistry.markReviewed(id);
-      ctx.print(`Reviewed Agent skill ${skill.id}.`);
+      ctx.print(formatSkillReceipt('Reviewed Agent skill', skill));
       return;
     }
     if (sub === 'stale') {
       const id = args[1];
       if (!id) {
-        ctx.print('Usage: /agent-skills stale <id> <reason...>');
+        ctx.print('Usage: /skills stale <id> <reason...>');
         return;
       }
       const skill = skillRegistry.markStale(id, args.slice(2).join(' '));
-      ctx.print(`Marked Agent skill ${skill.id} stale.`);
+      ctx.print(formatSkillReceipt('Marked Agent skill stale', skill));
       return;
     }
     if (sub === 'delete' || sub === 'remove') {
       const parsed = parseSkillArgs(args.slice(1));
       const id = parsed.rest[0];
       if (!id) {
-        ctx.print('Usage: /agent-skills delete <id> --yes');
+        ctx.print('Usage: /skills delete <id> --yes');
         return;
       }
       if (!parsed.yes) {
@@ -440,10 +517,10 @@ export async function runAgentSkillsRuntimeCommand(args: readonly string[], ctx:
         return;
       }
       const removed = skillRegistry.deleteSkill(id);
-      ctx.print(`Deleted Agent skill ${removed.id}: ${removed.name}`);
+      ctx.print(formatSkillReceipt('Deleted Agent skill', removed));
       return;
     }
-    ctx.print('Usage: /agent-skills [list|enabled|discover|import-discovered|search|show|create|update|enable|disable|review|stale|delete|bundle]');
+    ctx.print('Usage: /skills [list|enabled|attention|discover|import-discovered|search|show|create|update|enable|disable|review|stale|delete|bundle]');
   } catch (error) {
     printError(ctx, error);
   }
@@ -451,10 +528,10 @@ export async function runAgentSkillsRuntimeCommand(args: readonly string[], ctx:
 
 export function registerAgentSkillsRuntimeCommands(registry: CommandRegistry): void {
   registry.register({
-    name: 'agent-skills',
-    aliases: ['askills', 'local-skills', 'skills', 'skill'],
-    description: 'Manage local GoodVibes Agent skills',
-    usage: '[list|enabled|discover|import-discovered <name> --yes|search <query>|show <id>|create --name <name> --description <summary> --procedure <steps>|update <id> [--name ...] [--description ...] [--procedure ...]|enable <id>|disable <id>|review <id>|stale <id> <reason...>|delete <id> --yes|bundle ...]',
+    name: 'skills',
+    aliases: ['skill', 'agent-skills', 'askills', 'local-skills'],
+    description: 'Manage Agent-local skills',
+    usage: '[list|enabled|attention|discover|import-discovered <name> --yes|search <query>|show <id>|create --name <name> --description <summary> --procedure <steps> [--requires-env A,B] [--requires-command gh,jq]|update <id> [--name ...] [--description ...] [--procedure ...]|enable <id>|disable <id>|review <id>|stale <id> <reason...>|delete <id> --yes|bundle ...]',
     handler: runAgentSkillsRuntimeCommand,
   });
 }

package/src/input/commands/agent-workspace-runtime.ts

@@ -1,17 +1,34 @@
-import type { CommandRegistry } from '../command-registry.ts';
+import type { CommandContext, CommandRegistry } from '../command-registry.ts';
+import { AGENT_WORKSPACE_CATEGORY_IDS } from '../agent-workspace-types.ts';
+
+const AGENT_WORKSPACE_ARGS_HINT = `${AGENT_WORKSPACE_CATEGORY_IDS.join('|')}|connected-host`;
 
 export function registerAgentWorkspaceRuntimeCommands(registry: CommandRegistry): void {
+  function openAgentWorkspace(ctx: CommandContext, categoryId: string | undefined): void {
+    if (!ctx.openAgentWorkspace) {
+      ctx.print('Agent operator workspace is not available in this runtime.');
+      return;
+    }
+    ctx.openAgentWorkspace(categoryId);
+  }
+
   registry.register({
     name: 'agent',
     aliases: ['home', 'operator'],
     description: 'Open the GoodVibes Agent operator workspace',
+    usage: '[category]',
+    argsHint: AGENT_WORKSPACE_ARGS_HINT,
+    handler(args, ctx) {
+      openAgentWorkspace(ctx, args[0]);
+    },
+  });
+  registry.register({
+    name: 'notes',
+    aliases: ['scratchpad'],
+    description: 'Open Agent-local scratchpad notes in the operator workspace',
     usage: '',
     handler(_args, ctx) {
-      if (!ctx.openAgentWorkspace) {
-        ctx.print('Agent operator workspace is not available in this runtime.');
-        return;
-      }
-      ctx.openAgentWorkspace();
+      openAgentWorkspace(ctx, 'notes');
     },
   });
 }

package/src/input/commands/brief-runtime.ts

@@ -34,8 +34,12 @@ function plural(count: number, singular: string, pluralWord = `${singular}s`): s
   return `${count} ${count === 1 ? singular : pluralWord}`;
 }
 
+function countSetupGaps(items: readonly { readonly missingRequirementCount?: number }[]): number {
+  return items.filter((item) => (item.missingRequirementCount ?? 0) > 0).length;
+}
+
 function formatWorkPlanLine(total: number, counts: StatusCounts): string {
-  if (total === 0) return '  work plan: empty';
+  if (total === 0) return '  work plan empty';
   const active = counts.pending + counts.in_progress + counts.blocked;
   return [
     `  work plan: ${plural(total, 'item')}`,
@@ -48,8 +52,8 @@ function formatWorkPlanLine(total: number, counts: StatusCounts): string {
 }
 
 function formatWarnings(warnings: readonly string[]): readonly string[] {
-  if (warnings.length === 0) return ['  warnings: none'];
-  return ['  warnings:', ...warnings.slice(0, 4).map((warning) => `    - ${warning}`)];
+  if (warnings.length === 0) return ['  warnings none'];
+  return ['  warnings', ...warnings.slice(0, 4).map((warning) => `    - ${warning}`)];
 }
 
 export function formatAgentOperatorBriefing(ctx: CommandContext): string {
@@ -62,48 +66,74 @@ export function formatAgentOperatorBriefing(ctx: CommandContext): string {
   const setupBlocked = countReady(snapshot.setupChecklist, 'blocked');
   const readyChannels = snapshot.channels.filter((channel) => channel.ready).length;
   const enabledChannels = snapshot.channels.filter((channel) => channel.enabled).length;
+  const channelSetupGaps = snapshot.channels.filter((channel) => channel.enabled && !channel.ready).length;
+  const skillSetupGaps = countSetupGaps(snapshot.localSkills);
+  const skillBundleSetupGaps = countSetupGaps(snapshot.localSkillBundles);
+  const routineSetupGaps = countSetupGaps(snapshot.localRoutines);
+  const voiceSetupNeedsReview = snapshot.voiceSurfaceEnabled && snapshot.voiceMediaReadiness.selectedTtsProviderStatus !== 'ready';
+  const mediaSetupNeedsReview = snapshot.mediaProviderCount > 0 && snapshot.voiceMediaReadiness.readyMediaProviderCount === 0;
+  const hasLocalSkillBehavior = snapshot.localSkillCount > 0 || snapshot.localSkillBundleCount > 0;
 
   const nextActions = [
     snapshot.provider === 'unknown' || snapshot.model === 'unknown'
-      ? 'Choose the assistant model with /model.'
+      ? 'Choose the assistant model from Agent Workspace -> Home -> Choose model.'
       : '',
     snapshot.localMemoryCount === 0
-      ? 'Store durable non-secret facts with /memory add or the Agent workspace memory form.'
+      ? 'Store durable non-secret facts from Agent Workspace -> Memory -> Add memory.'
       : snapshot.localMemoryReviewQueueCount > 0
-        ? `Review ${plural(snapshot.localMemoryReviewQueueCount, 'memory record')} with /memory queue.`
-        : '',
-    snapshot.localSkillCount === 0 && snapshot.localSkillBundleCount === 0
-      ? 'Create reusable procedures with /agent-skills create or import reviewed skill files.'
-      : snapshot.activeSkillCount === 0
-        ? 'Enable reviewed skills or bundles with /agent-skills enabled and /agent-skills bundle enabled.'
+        ? `Review ${plural(snapshot.localMemoryReviewQueueCount, 'memory record')} from Agent Workspace -> Memory -> Review queue.`
         : '',
+    !hasLocalSkillBehavior
+      ? 'Create reusable procedures from Agent Workspace -> Skills or import reviewed skill files.'
+      : '',
+    skillSetupGaps > 0
+      ? `Resolve ${plural(skillSetupGaps, 'skill')} with setup gaps from Agent Workspace -> Skills.`
+      : '',
+    skillBundleSetupGaps > 0
+      ? `Resolve ${plural(skillBundleSetupGaps, 'skill bundle')} with setup gaps from Agent Workspace -> Skills.`
+      : '',
+    hasLocalSkillBehavior && skillSetupGaps === 0 && skillBundleSetupGaps === 0 && snapshot.activeSkillCount === 0
+      ? 'Enable reviewed skills or bundles from Agent Workspace -> Skills.'
+      : '',
     snapshot.localRoutineCount === 0
-      ? 'Create repeatable workflows with /routines create; promote schedules only with explicit confirmation.'
-      : snapshot.enabledRoutineCount === 0
-        ? 'Enable reviewed routines with /routines enable.'
+      ? 'Create repeatable workflows from Agent Workspace -> Routines; promote schedules only with explicit confirmation.'
+      : routineSetupGaps > 0
+        ? `Resolve ${plural(routineSetupGaps, 'routine')} with setup gaps from Agent Workspace -> Routines.`
+        : snapshot.enabledRoutineCount === 0
+        ? 'Enable reviewed routines from Agent Workspace -> Routines.'
         : '',
-    'Use /knowledge status, /knowledge search, and explicit ingest forms for Agent Knowledge only.',
-    'Use /delegate only for explicit build, fix, implementation, or review handoff to GoodVibes TUI.',
+    channelSetupGaps > 0
+      ? `Review ${plural(channelSetupGaps, 'enabled channel')} needing setup from Agent Workspace -> Channels.`
+      : '',
+    voiceSetupNeedsReview
+      ? 'Review voice setup from Agent Workspace -> Voice & Media before relying on spoken replies.'
+      : '',
+    mediaSetupNeedsReview
+      ? 'Review media provider setup from Agent Workspace -> Voice & Media before relying on image or media workflows.'
+      : '',
+    'Use Agent Workspace -> Knowledge for Agent Knowledge status, search, and explicit ingest forms.',
+    'Use Agent Workspace -> Build Delegation only for explicit build, fix, implementation, or review handoff to GoodVibes TUI.',
   ].filter((line): line is string => line.length > 0);
 
   return [
     'Agent Briefing',
     `  chat route: ${snapshot.provider} / ${snapshot.modelDisplayName}`,
-    `  session: ${snapshot.sessionId}`,
-    `  profile: ${snapshot.activeRuntimeProfile}`,
-    `  policy: ${snapshot.executionPolicy}; WRFC ${snapshot.wrfcPolicy}`,
-    `  knowledge: ${snapshot.knowledgeRoute} (${snapshot.knowledgeIsolation}; no fallback)`,
+    `  session ${snapshot.sessionId}`,
+    `  profile ${snapshot.activeRuntimeProfile}`,
+    `  policy ${snapshot.executionPolicy}; delegated review ${snapshot.delegatedReviewPolicy}`,
+    `  knowledge ${snapshot.knowledgeRoute} (${snapshot.knowledgeIsolation}; no fallback)`,
     '',
     'Readiness',
-    `  setup: ${setupReady}/${snapshot.setupChecklist.length} ready; ${setupRecommended} recommended; ${setupBlocked} blocked`,
+    `  setup ${setupReady}/${snapshot.setupChecklist.length} ready; ${setupRecommended} recommended; ${setupBlocked} blocked`,
     `  local memory: ${plural(snapshot.localMemoryCount, 'record')}; prompt-active ${snapshot.localMemoryPromptActiveCount}; review queue ${snapshot.localMemoryReviewQueueCount}`,
+    `  scratchpad notes: ${plural(snapshot.localNoteCount, 'note')}; review queue ${snapshot.localNoteReviewQueueCount}`,
     `  personas: ${plural(snapshot.localPersonaCount, 'persona')}; active ${snapshot.activePersonaName}`,
-    `  skills: ${snapshot.enabledSkillCount}/${snapshot.localSkillCount} enabled; bundles ${snapshot.enabledSkillBundleCount}/${snapshot.localSkillBundleCount}; active ${snapshot.activeSkillCount}`,
-    `  routines: ${snapshot.enabledRoutineCount}/${snapshot.localRoutineCount} enabled`,
-    `  channels: ${readyChannels}/${snapshot.channels.length} ready; ${enabledChannels} enabled`,
+    `  skills: ${snapshot.enabledSkillCount}/${snapshot.localSkillCount} enabled; bundles ${snapshot.enabledSkillBundleCount}/${snapshot.localSkillBundleCount}; active ${snapshot.activeSkillCount}; setup gaps ${skillSetupGaps} skill, ${skillBundleSetupGaps} bundle`,
+    `  routines: ${snapshot.enabledRoutineCount}/${snapshot.localRoutineCount} enabled; setup gaps ${routineSetupGaps}`,
+    `  channels: ${readyChannels}/${snapshot.channels.length} ready; ${enabledChannels} enabled; setup gaps ${channelSetupGaps}`,
     `  voice/media: ${snapshot.voiceProviderCount} voice, ${snapshot.mediaProviderCount} media; browser tools ${snapshot.voiceMediaReadiness.browserToolState}`,
     formatWorkPlanLine(workPlan.total, workPlan.counts),
-    `  schedules: ${enabledJobs}/${jobs.length} visible jobs enabled`,
+    `  schedules ${enabledJobs}/${jobs.length} visible jobs enabled`,
     '',
     'Next Actions',
     ...nextActions.map((line) => `  - ${line}`),