@pellux/goodvibes-agent 0.1.114 → 0.1.117

package/src/agent/skill-registry.ts

@@ -1,11 +1,31 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { dirname } from 'node:path';
+import { accessSync, constants, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { delimiter, dirname, join } from 'node:path';
 import type { ShellPathService } from '@/runtime/index.ts';
 import { GOODVIBES_AGENT_SURFACE_ROOT } from '../config/surface.ts';
 import { assertNoSecretLikeText } from './persona-registry.ts';
 
 export type AgentSkillSource = 'user' | 'agent' | 'imported' | 'system';
 export type AgentSkillReviewState = 'fresh' | 'reviewed' | 'stale';
+export type AgentSkillRequirementKind = 'env' | 'command';
+
+export interface AgentSkillRequirement {
+  readonly kind: AgentSkillRequirementKind;
+  readonly name: string;
+  readonly description?: string;
+}
+
+export interface AgentSkillReadiness {
+  readonly ready: boolean;
+  readonly met: readonly AgentSkillRequirement[];
+  readonly missing: readonly AgentSkillRequirement[];
+}
+
+export interface AgentSkillBundleReadiness {
+  readonly ready: boolean;
+  readonly includedSkills: readonly AgentSkillRecord[];
+  readonly missingSkillIds: readonly string[];
+  readonly missingRequirements: readonly AgentSkillRequirement[];
+}
 
 export interface AgentSkillRecord {
   readonly id: string;
@@ -14,6 +34,7 @@ export interface AgentSkillRecord {
   readonly procedure: string;
   readonly triggers: readonly string[];
   readonly tags: readonly string[];
+  readonly requirements: readonly AgentSkillRequirement[];
   readonly enabled: boolean;
   readonly source: AgentSkillSource;
   readonly provenance: string;
@@ -45,6 +66,7 @@ export interface AgentSkillCreateInput {
   readonly procedure: string;
   readonly triggers?: readonly string[];
   readonly tags?: readonly string[];
+  readonly requirements?: readonly AgentSkillRequirement[];
   readonly enabled?: boolean;
   readonly source?: AgentSkillSource;
   readonly provenance?: string;
@@ -65,6 +87,7 @@ export interface AgentSkillUpdateInput {
   readonly procedure?: string;
   readonly triggers?: readonly string[];
   readonly tags?: readonly string[];
+  readonly requirements?: readonly AgentSkillRequirement[];
   readonly provenance?: string;
 }
 
@@ -105,6 +128,11 @@ function readStringArray(value: unknown): string[] {
   return value.filter((entry): entry is string => typeof entry === 'string').map((entry) => entry.trim()).filter(Boolean);
 }
 
+function readRequirementKind(value: unknown): AgentSkillRequirementKind | null {
+  if (value === 'env' || value === 'command') return value;
+  return null;
+}
+
 function normalizeName(name: string): string {
   return name.trim().replace(/\s+/g, ' ');
 }
@@ -123,6 +151,48 @@ function normalizeList(values: readonly string[] | undefined): string[] {
   return result;
 }
 
+function validateRequirementName(requirement: AgentSkillRequirement): void {
+  if (requirement.kind === 'env' && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(requirement.name)) {
+    throw new Error(`Invalid skill env requirement: ${requirement.name}`);
+  }
+  if (requirement.kind === 'command' && !/^[A-Za-z0-9._+-]+$/.test(requirement.name)) {
+    throw new Error(`Invalid skill command requirement: ${requirement.name}`);
+  }
+}
+
+function normalizeRequirements(values: readonly AgentSkillRequirement[] | undefined): AgentSkillRequirement[] {
+  const seen = new Set<string>();
+  const result: AgentSkillRequirement[] = [];
+  for (const value of values ?? []) {
+    const kind = readRequirementKind(value.kind);
+    const name = typeof value.name === 'string' ? value.name.trim() : '';
+    if (!kind || !name) continue;
+    const description = typeof value.description === 'string' ? value.description.trim() : '';
+    const requirement: AgentSkillRequirement = {
+      kind,
+      name,
+      ...(description ? { description } : {}),
+    };
+    validateRequirementName(requirement);
+    const key = `${requirement.kind}:${requirement.name.toLowerCase()}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push(requirement);
+  }
+  return result;
+}
+
+function parseRequirements(value: unknown): AgentSkillRequirement[] {
+  if (!Array.isArray(value)) return [];
+  return normalizeRequirements(value
+    .filter(isRecord)
+    .map((entry) => ({
+      kind: readRequirementKind(entry.kind) ?? 'env',
+      name: readString(entry.name).trim(),
+      description: readString(entry.description).trim(),
+    })));
+}
+
 function slugify(value: string): string {
   const slug = value.trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
   return slug || 'skill';
@@ -132,6 +202,23 @@ function nowIso(): string {
   return new Date().toISOString();
 }
 
+function canExecute(path: string): boolean {
+  try {
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function commandExists(command: string, pathValue: string | undefined): boolean {
+  if (!pathValue) return false;
+  return pathValue
+    .split(delimiter)
+    .filter(Boolean)
+    .some((pathEntry) => canExecute(join(pathEntry, command)));
+}
+
 function parseSkill(value: unknown): AgentSkillRecord | null {
   if (!isRecord(value)) return null;
   const id = readString(value.id).trim();
@@ -150,6 +237,7 @@ function parseSkill(value: unknown): AgentSkillRecord | null {
     procedure,
     triggers: readStringArray(value.triggers),
     tags: readStringArray(value.tags),
+    requirements: parseRequirements(value.requirements),
     enabled: value.enabled === true,
     source,
     provenance: readString(value.provenance, source).trim() || source,
@@ -206,14 +294,16 @@ function formatStore(store: SkillStoreFile): string {
   return `${JSON.stringify(store, null, 2)}\n`;
 }
 
-export function skillStorePath(shellPaths: ShellPathService): string {
+type AgentLocalStorePaths = Pick<ShellPathService, 'resolveUserPath'>;
+
+export function skillStorePath(shellPaths: AgentLocalStorePaths): string {
   return shellPaths.resolveUserPath(GOODVIBES_AGENT_SURFACE_ROOT, 'skills', 'skills.json');
 }
 
 export class AgentSkillRegistry {
   public constructor(private readonly storePath: string) {}
 
-  public static fromShellPaths(shellPaths: ShellPathService): AgentSkillRegistry {
+  public static fromShellPaths(shellPaths: AgentLocalStorePaths): AgentSkillRegistry {
     return new AgentSkillRegistry(skillStorePath(shellPaths));
   }
 
@@ -284,7 +374,8 @@ export class AgentSkillRegistry {
     const description = input.description.trim();
     const procedure = input.procedure.trim();
     this.validateRequired(name, description, procedure);
-    assertNoSecretLikeText([name, description, procedure, ...(input.tags ?? []), ...(input.triggers ?? [])]);
+    const requirements = normalizeRequirements(input.requirements);
+    assertNoSecretLikeText([name, description, procedure, ...(input.tags ?? []), ...(input.triggers ?? []), ...requirements.flatMap((requirement) => [requirement.name, requirement.description ?? ''])]);
     const duplicate = store.skills.find((skill) => skill.name.toLowerCase() === name.toLowerCase());
     if (duplicate) throw new Error(`Skill already exists: ${duplicate.id}`);
     const timestamp = nowIso();
@@ -295,6 +386,7 @@ export class AgentSkillRegistry {
       procedure,
       triggers: normalizeList(input.triggers),
       tags: normalizeList(input.tags),
+      requirements,
       enabled: input.enabled === true,
       source: input.source ?? 'user',
       provenance: input.provenance?.trim() || input.source || 'user',
@@ -340,7 +432,8 @@ export class AgentSkillRegistry {
     const description = input.description === undefined ? existing.description : input.description.trim();
     const procedure = input.procedure === undefined ? existing.procedure : input.procedure.trim();
     this.validateRequired(name, description, procedure);
-    assertNoSecretLikeText([name, description, procedure, ...(input.tags ?? []), ...(input.triggers ?? [])]);
+    const requirements = input.requirements === undefined ? existing.requirements : normalizeRequirements(input.requirements);
+    assertNoSecretLikeText([name, description, procedure, ...(input.tags ?? []), ...(input.triggers ?? []), ...requirements.flatMap((requirement) => [requirement.name, requirement.description ?? ''])]);
     const duplicate = store.skills.find((skill) => skill.id !== existing.id && skill.name.toLowerCase() === name.toLowerCase());
     if (duplicate) throw new Error(`Skill already exists: ${duplicate.id}`);
     const updated: AgentSkillRecord = {
@@ -350,6 +443,7 @@ export class AgentSkillRegistry {
       procedure,
       triggers: input.triggers === undefined ? existing.triggers : normalizeList(input.triggers),
       tags: input.tags === undefined ? existing.tags : normalizeList(input.tags),
+      requirements,
       provenance: input.provenance === undefined ? existing.provenance : input.provenance.trim() || existing.provenance,
       reviewState: 'fresh',
       staleReason: undefined,
@@ -583,6 +677,80 @@ export class AgentSkillRegistry {
   }
 }
 
+export function buildAgentSkillRequirements(input: {
+  readonly env?: readonly string[];
+  readonly commands?: readonly string[];
+}): readonly AgentSkillRequirement[] {
+  return normalizeRequirements([
+    ...(input.env ?? []).map((name) => ({ kind: 'env' as const, name })),
+    ...(input.commands ?? []).map((name) => ({ kind: 'command' as const, name })),
+  ]);
+}
+
+export function normalizeAgentSkillRequirements(values: readonly AgentSkillRequirement[] | undefined): readonly AgentSkillRequirement[] {
+  return normalizeRequirements(values);
+}
+
+export function formatAgentSkillRequirement(requirement: AgentSkillRequirement): string {
+  return `${requirement.kind}:${requirement.name}`;
+}
+
+export function evaluateAgentSkillReadiness(
+  skill: Pick<AgentSkillRecord, 'requirements'>,
+  options: {
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly pathValue?: string;
+  } = {},
+): AgentSkillReadiness {
+  const env = options.env ?? process.env;
+  const pathValue = options.pathValue ?? env.PATH;
+  const met: AgentSkillRequirement[] = [];
+  const missing: AgentSkillRequirement[] = [];
+  for (const requirement of skill.requirements) {
+    const present = requirement.kind === 'env'
+      ? typeof env[requirement.name] === 'string' && (env[requirement.name] ?? '').length > 0
+      : commandExists(requirement.name, pathValue);
+    if (present) met.push(requirement);
+    else missing.push(requirement);
+  }
+  return { ready: missing.length === 0, met, missing };
+}
+
+export function evaluateAgentSkillBundleReadiness(
+  bundle: Pick<AgentSkillBundleRecord, 'skillIds'>,
+  skills: readonly AgentSkillRecord[],
+  options: {
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly pathValue?: string;
+  } = {},
+): AgentSkillBundleReadiness {
+  const skillById = new Map(skills.map((skill) => [skill.id, skill]));
+  const includedSkills: AgentSkillRecord[] = [];
+  const missingSkillIds: string[] = [];
+  const missingRequirements: AgentSkillRequirement[] = [];
+  const seenRequirements = new Set<string>();
+  for (const skillId of bundle.skillIds) {
+    const skill = skillById.get(skillId);
+    if (!skill) {
+      missingSkillIds.push(skillId);
+      continue;
+    }
+    includedSkills.push(skill);
+    for (const requirement of evaluateAgentSkillReadiness(skill, options).missing) {
+      const key = `${requirement.kind}:${requirement.name.toLowerCase()}`;
+      if (seenRequirements.has(key)) continue;
+      seenRequirements.add(key);
+      missingRequirements.push(requirement);
+    }
+  }
+  return {
+    ready: missingSkillIds.length === 0 && missingRequirements.length === 0,
+    includedSkills,
+    missingSkillIds,
+    missingRequirements,
+  };
+}
+
 export function buildEnabledSkillsPrompt(shellPaths: ShellPathService): string | null {
   const snapshot = AgentSkillRegistry.fromShellPaths(shellPaths).snapshot();
   const active = snapshot.activeSkills;
@@ -591,18 +759,27 @@ export function buildEnabledSkillsPrompt(shellPaths: ShellPathService): string |
     '## Enabled GoodVibes Agent Skills',
     'Use these local reusable procedures inside the same serial assistant conversation when they fit the user request.',
     '',
-    ...snapshot.enabledBundles.slice(0, 4).flatMap((bundle) => [
-      `### Skill Bundle: ${bundle.name}`,
-      `Description: ${bundle.description}`,
-      `Review state: ${bundle.reviewState}`,
-      `Included skills: ${bundle.skillIds.join(', ')}`,
-      '',
-    ]),
+    ...snapshot.enabledBundles.slice(0, 4).flatMap((bundle) => {
+      const readiness = evaluateAgentSkillBundleReadiness(bundle, snapshot.skills);
+      const missing = [
+        ...readiness.missingRequirements.map(formatAgentSkillRequirement),
+        ...readiness.missingSkillIds.map((skillId) => `skill:${skillId}`),
+      ];
+      return [
+        `### Skill Bundle: ${bundle.name}`,
+        `Description: ${bundle.description}`,
+        `Review state: ${bundle.reviewState}`,
+        `Readiness: ${readiness.ready ? 'ready' : `missing ${missing.join(', ')}`}`,
+        `Included skills: ${bundle.skillIds.join(', ')}`,
+        '',
+      ];
+    }),
     ...active.slice(0, 8).flatMap((skill) => [
       `### ${skill.name}`,
       `Description: ${skill.description}`,
       `Review state: ${skill.reviewState}`,
       `Triggers: ${skill.triggers.join(', ') || '(manual)'}`,
+      `Readiness: ${evaluateAgentSkillReadiness(skill).ready ? 'ready' : `missing ${evaluateAgentSkillReadiness(skill).missing.map(formatAgentSkillRequirement).join(', ')}`}`,
       skill.procedure,
       '',
     ]),

package/src/cli/agent-knowledge-command.ts

@@ -493,7 +493,7 @@ export async function handleCompatCommand(runtime: CliCommandRuntime): Promise<C
     ok: versionCompatible && knowledgeRouteReady,
     packageVersion: metadata.version,
     sdkPin: metadata.sdkVersion,
-    daemon: {
+    connectedHost: {
       baseUrl: connection.baseUrl,
       status: daemon.status,
       version: daemonVersion,
@@ -518,7 +518,7 @@ export async function handleCompatCommand(runtime: CliCommandRuntime): Promise<C
     `  version compatible: ${yesNo(versionCompatible)}`,
     `  operator token: ${connection.token ? 'present' : 'missing'} (${connection.tokenPath})`,
     `  Agent knowledge route: ${knowledgeRouteReady ? 'ready' : `not ready (${knowledgeRoute.ok ? 'unknown' : knowledgeRoute.kind})`}`,
-    ...(versionCompatible ? [] : ['  next: update connected GoodVibes services so /status matches the Agent SDK pin.']),
+    ...(versionCompatible ? [] : ['  next: update the connected GoodVibes host so /status matches the Agent SDK pin.']),
   ].join('\n');
   return {
     output: runtime.cli.flags.outputFormat === 'json' ? JSON.stringify(value, null, 2) : text,

package/src/cli/agent-knowledge-format.ts

@@ -367,10 +367,10 @@ export function formatFailure(failure: AgentKnowledgeFailureLike, json: boolean)
       ? `  versions: runtime=${failure.daemonVersion} expected=${failure.expectedSdkVersion}`
       : null,
     failure.kind === 'version_mismatch'
-      ? '  next: update connected GoodVibes services so /status matches the Agent SDK pin.'
+      ? '  next: update the connected GoodVibes host so /status matches the Agent SDK pin.'
       : null,
     failure.kind === 'daemon_route_unavailable'
-      ? '  next: update connected GoodVibes services to the SDK version required by this Agent package.'
+      ? '  next: update the connected GoodVibes host to the SDK version required by this Agent package.'
       : null,
   ].filter((line): line is string => Boolean(line)).join('\n');
 }

package/src/cli/agent-knowledge-runtime.ts

@@ -94,7 +94,7 @@ export async function classifyKnowledgeError(error: unknown, connection: AgentDa
       return {
         ok: false,
         kind: 'version_mismatch',
-        error: `Connected GoodVibes service SDK version ${daemonVersion} does not match Agent SDK pin ${metadata.sdkVersion}; Agent Knowledge route is unavailable.`,
+        error: `Connected GoodVibes host SDK version ${daemonVersion} does not match Agent SDK pin ${metadata.sdkVersion}; Agent Knowledge route is unavailable.`,
         baseUrl: connection.baseUrl,
         route,
         daemonVersion,

package/src/cli/bundle-command.ts

@@ -132,7 +132,7 @@ export async function handleBundleCommand(runtime: CliCommandRuntime): Promise<C
     const summary = inspectBundle(sourcePath, parsed.value);
     return {
       output: formatJsonOrText(runtime, summary, [
-        'GoodVibes bundle',
+        'GoodVibes Agent support bundle',
         `  type: ${summary.type}`,
         `  version: ${summary.version}`,
         `  path: ${summary.path}`,

package/src/cli/entrypoint.ts

@@ -25,7 +25,7 @@ import {
 import { buildCliServicePosture } from './service-posture.ts';
 import { inspectCliExternalRuntime } from './external-runtime.ts';
 import { GOODVIBES_AGENT_SURFACE_ROOT } from '../config/surface.ts';
-import { resolveAgentRuntimeProfileHome } from '../agent/runtime-profile.ts';
+import { resolveAgentRuntimeProfileHome, resolveSelectedAgentRuntimeProfileHome } from '../agent/runtime-profile.ts';
 
 type ShellEntrypointOwnership = {
   readonly workingDirectory: string;
@@ -52,14 +52,20 @@ export type PreparedShellCliRuntime = {
   readonly bootstrapHomeDirectory: string;
 };
 
-function resolveShellEntrypointOwnership(
+export function resolveShellEntrypointOwnership(
   roots: ShellEntrypointRoots,
   workingDirOverride?: string,
-  agentProfile?: string,
+  options: {
+    readonly agentProfile?: string;
+    readonly useSelectedProfile: boolean;
+  } = { useSelectedProfile: true },
 ): ShellEntrypointOwnership {
-  const homeDirectory = agentProfile
-    ? resolveAgentRuntimeProfileHome(roots.homeDirectory, agentProfile).homeDirectory
-    : roots.homeDirectory;
+  const selectedProfile = options.agentProfile
+    ? resolveAgentRuntimeProfileHome(roots.homeDirectory, options.agentProfile)
+    : options.useSelectedProfile
+      ? resolveSelectedAgentRuntimeProfileHome(roots.homeDirectory)
+      : null;
+  const homeDirectory = selectedProfile?.homeDirectory ?? roots.homeDirectory;
   return {
     workingDirectory: workingDirOverride ?? roots.defaultWorkingDirectory,
     homeDirectory,
@@ -103,7 +109,10 @@ export async function prepareShellCliRuntime(
     ownership = resolveShellEntrypointOwnership(
       roots,
       cli.flags.workingDir ?? (cli.command === 'tui' ? cli.commandArgs[0] : undefined),
-      cli.command === 'profiles' ? undefined : cli.flags.agentProfile,
+      {
+        agentProfile: cli.command === 'profiles' ? undefined : cli.flags.agentProfile,
+        useSelectedProfile: cli.command !== 'profiles',
+      },
     );
   } catch (error) {
     console.error(error instanceof Error ? error.message : String(error));

package/src/cli/help.ts

@@ -37,12 +37,12 @@ export function renderGoodVibesHelp(binary = 'goodvibes-agent'): string {
     '  /setup                    Open setup/config flows',
     '  /model                    Choose provider and model',
     '  /knowledge                Use isolated Agent Knowledge',
-  '  /personas, /skills        Tune local Agent behavior',
-  '  /routines                 Run local routines in the main conversation',
-  '  /schedule remind          Create confirmed reminders or inspect schedules',
-  '  /delegate                 Explicitly hand build/fix/review work to GoodVibes TUI',
+    '  /personas, /skills        Tune local Agent behavior',
+    '  /routines                 Run local routines in the main conversation',
+    '  /schedule remind          Create confirmed reminders or inspect schedules',
+    '  /delegate                 Explicitly hand build/fix/review work to GoodVibes TUI',
     '',
-    'Commands:',
+    'Scriptable mirrors:',
     '  run|exec [prompt]          Run non-interactively with text/json/stream-json output',
     '  status                     Print config, provider, auth, and setup posture',
     '  doctor                     Print status plus setup warnings',
@@ -55,7 +55,7 @@ export function renderGoodVibesHelp(binary = 'goodvibes-agent'): string {
     '  memory                     Manage Agent-owned durable memory records',
     '  routines                   Inspect local routines and explicitly promote one to a connected schedule',
     '  auth                       Inspect Agent auth posture and connection token state',
-    '  compat                     Inspect Agent SDK pin, connected service version, and Agent Knowledge route readiness',
+    '  compat                     Inspect Agent SDK pin, connected host version, and Agent Knowledge route readiness',
     '  knowledge                  Use isolated Agent Knowledge/Wiki routes',
     '  ask|search                 Shortcuts for isolated Agent Knowledge ask/search',
     '  delegate                   Explicitly delegate build/fix/review work to GoodVibes TUI',
@@ -106,7 +106,7 @@ export function renderGoodVibesHelp(binary = 'goodvibes-agent'): string {
     `  ${binary} profiles create household --template household --yes`,
     `  ${binary} --agent-profile household`,
     `  ${binary} personas create --name "Travel Planner" --description "Plan trips" --body "Compare options before booking"`,
-    `  ${binary} skills create --name "Daily Brief" --description "Summarize operator state" --procedure "Review Agent Knowledge, work plans, approvals, and routines" --enabled`,
+    `  ${binary} skills create --name "Daily Brief" --description "Summarize operator state" --procedure "Review Agent Knowledge, work plans, approvals, and routines" --requires-env GOODVIBES_AGENT_TOKEN --requires-command gh --enabled`,
     `  ${binary} memory add fact "Prefers concise morning briefings" --scope project --tags preference`,
     `  ${binary} memory search "morning briefings"`,
     `  ${binary} routines promote daily-operations-sweep --cron "0 9 * * *" --timezone America/Chicago --yes`,
@@ -138,12 +138,12 @@ const COMMAND_HELP: Record<string, CommandHelp> = {
   },
   setup: {
     usage: ['setup', 'setup status', 'onboarding', 'onboarding status'],
-    summary: 'Open Agent setup, or inspect whether setup has already been shown for this user.',
+    summary: 'Open Agent setup, or inspect whether setup has already been applied for this user.',
     examples: ['setup', 'setup status', 'onboarding status'],
   },
   status: {
     usage: ['status', 'status --json', '--runtime-url http://127.0.0.1:3421 status'],
-    summary: 'Print Agent config, provider, auth, connected-service state, and setup posture.',
+    summary: 'Print Agent config, provider, auth, connected-host state, and setup posture.',
     examples: ['status', 'status --json', '--runtime-url http://127.0.0.1:3421 status'],
   },
   doctor: {
@@ -157,9 +157,9 @@ const COMMAND_HELP: Record<string, CommandHelp> = {
     examples: ['providers', 'providers inspect openai-subscriber', 'providers use openai openai:gpt-5.4'],
   },
   profiles: {
-    usage: ['profiles list', 'profiles templates', 'profiles templates export <id> <path> --yes', 'profiles templates import <path> --yes', 'profiles show <name>', 'profiles create <name> [--template <id>] --yes', 'profiles delete <name> --yes', '--agent-profile <name>'],
-    summary: 'Create and inspect isolated Agent profile homes, with starter templates for household, research, travel, operations, personal productivity, and local imported starters. A profile changes Agent-local config, sessions, memory, personas, skills, routines, and setup paths without changing connected GoodVibes services.',
-    examples: ['profiles templates', 'profiles templates export research ./research-starter.json --yes', 'profiles templates import ./research-starter.json --yes', 'profiles create household --template household --yes', '--agent-profile household status'],
+    usage: ['profiles list', 'profiles default', 'profiles use <name> --yes', 'profiles default clear --yes', 'profiles templates', 'profiles templates from-discovered <id> --yes', 'profiles create-from-discovered <name> --yes', 'profiles templates export <id> <path> --yes', 'profiles templates import <path> --yes', 'profiles show <name>', 'profiles create <name> [--template <id>] --yes', 'profiles delete <name> --yes', '--agent-profile <name>'],
+    summary: 'Create and inspect isolated Agent profile homes, with starter templates for household, research, travel, operations, personal productivity, and local imported starters. A profile changes Agent-local config, sessions, memory, personas, skills, routines, and setup paths without changing the connected GoodVibes host.',
+    examples: ['profiles templates', 'profiles create household --template household --yes', 'profiles use household --yes', 'profiles default', 'profiles create-from-discovered research-desk --yes', 'profiles templates from-discovered research-desk --yes', 'profiles templates export research ./research-starter.json --yes', 'profiles templates import ./research-starter.json --yes', '--agent-profile household status'],
   },
   personas: {
     usage: [
@@ -192,25 +192,28 @@ const COMMAND_HELP: Record<string, CommandHelp> = {
       'skills list',
       'skills enabled',
       'skills active',
+      'skills attention',
       'skills discover',
       'skills import-discovered <name> [--enabled] --yes',
       'skills search <query>',
       'skills show <id>',
-      'skills create --name <name> --description <summary> --procedure <steps> [--tags a,b] [--triggers a,b] [--enabled]',
-      'skills update <id> [--name <name>] [--description <summary>] [--procedure <steps>] [--tags a,b] [--triggers a,b]',
+      'skills create --name <name> --description <summary> --procedure <steps> [--tags a,b] [--triggers a,b] [--requires-env A,B] [--requires-command gh,jq] [--enabled]',
+      'skills update <id> [--name <name>] [--description <summary>] [--procedure <steps>] [--tags a,b] [--triggers a,b] [--requires-env A,B] [--requires-command gh,jq]',
       'skills enable <id>',
       'skills disable <id>',
       'skills review <id>',
       'skills stale <id> <reason>',
       'skills delete <id> --yes',
-      'skills bundle [list|enabled|show|create|update|enable|disable|review|stale|delete]',
+      'skills bundle [list|enabled|attention|show|create|update|enable|disable|review|stale|delete]',
     ],
     summary: 'Manage reusable Agent-local procedures and skill bundles for the main conversation.',
     examples: [
       'skills list',
+      'skills attention',
+      'skills bundle attention',
       'skills discover',
       'skills import-discovered "Daily Brief" --enabled --yes',
-      'skills create --name "Daily Brief" --description "Summarize operator state" --procedure "Review Agent Knowledge, work plans, approvals, and routines" --enabled',
+      'skills create --name "Daily Brief" --description "Summarize operator state" --procedure "Review Agent Knowledge, work plans, approvals, and routines" --requires-env GOODVIBES_AGENT_TOKEN --requires-command gh --enabled',
       'skills bundle create --name "Ops Pack" --description "Daily operations bundle" --skills daily-brief --enabled',
       'skills delete daily-brief --yes',
     ],
@@ -247,20 +250,24 @@ const COMMAND_HELP: Record<string, CommandHelp> = {
     usage: [
       'routines list',
       'routines enabled',
+      'routines attention',
       'routines discover',
       'routines import-discovered <name> [--enabled] --yes',
       'routines show <id>',
+      'routines create --name <name> --description <summary> --steps <steps> [--tags a,b] [--triggers a,b] [--requires-env A,B] [--requires-command gh,jq] [--enabled]',
       'routines receipts',
       'routines reconcile',
       'routines receipt <receipt-id>',
       'routines promote <id> (--cron <expr>|--every <interval>|--at <iso-time>) [--timezone <tz>] [--name <schedule-name>] [--provider <id>] [--model <model>] [--delivery-channel <channel[:route[:label]]>|--delivery-route <route[:label]>|--delivery-webhook <url>|--delivery-link <url>] [--disabled] --yes',
     ],
-    summary: 'Inspect and import Agent-local routines, review local promotion receipts, reconcile receipts against live connected schedules, and explicitly promote a reviewed routine into a GoodVibes schedule. Without --yes, promote only prints the schedules.create preview.',
+    summary: 'Inspect, create, and import Agent-local routines with setup readiness. The same routine workflow is available in the TUI through /routines and the Agent workspace. GoodVibes schedule promotion is explicit. Without --yes, promotion only prints the preview.',
     examples: [
       'routines list',
+      'routines attention',
       'routines discover',
       'routines import-discovered "Daily Brief" --enabled --yes',
       'routines show daily-operations-sweep',
+      'routines create --name "Daily Sweep" --description "Review operator state" --steps "Check tasks, approvals, channels, and Agent Knowledge" --requires-env GOODVIBES_AGENT_TOKEN',
       'routines receipts',
       'routines reconcile',
       'routines promote daily-operations-sweep --cron "0 9 * * *" --timezone America/Chicago --delivery-channel slack --yes',
@@ -348,7 +355,7 @@ const COMMAND_HELP: Record<string, CommandHelp> = {
   },
   tasks: {
     usage: ['tasks list', 'tasks show <taskId>'],
-    summary: 'Inspect connected-service task summaries. Agent blocks service-owned task submission; use run for one-shot work or delegate for explicit build/fix/review handoff.',
+    summary: 'Inspect connected-host task summaries. Agent blocks host-owned task submission; use run for one-shot work or delegate for explicit build/fix/review handoff.',
     examples: ['tasks list', 'tasks show task-123', 'run "check provider readiness"', 'delegate "fix the failing tests"'],
   },
   bundle: {
@@ -402,7 +409,7 @@ export function renderGoodVibesCommandHelp(topic: string, binary = 'goodvibes-ag
     ].join('\n');
   }
   return [
-    `GoodVibes ${normalized}`,
+    `GoodVibes Agent ${normalized}`,
     '',
     help.summary,
     '',