@pellux/goodvibes-agent 0.1.106 → 0.1.108

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

@@ -221,6 +221,51 @@ export function formatConnectors(data: unknown): string {
   ].join('\n');
 }
 
+export function formatConnector(data: unknown, id: string): string {
+  const record = isRecord(data) ? data : {};
+  const connector = isRecord(record.connector) ? record.connector : record;
+  const connectorId = cleanInline(connector.id) || id;
+  const name = cleanInline(connector.displayName) || connectorId;
+  const description = cleanInline(connector.description);
+  const sourceType = cleanInline(connector.sourceType);
+  const capabilities = readArray(connector, 'capabilities').map(cleanInline).filter(Boolean);
+  const examples = readArray(connector, 'examples');
+  return [
+    `Agent Knowledge connector: ${connectorId}`,
+    `  name: ${name}`,
+    sourceType ? `  sourceType: ${sourceType}` : null,
+    description ? `  description: ${description}` : null,
+    capabilities.length > 0 ? `  capabilities: ${capabilities.join(', ')}` : null,
+    `  examples: ${examples.length}`,
+    '  route: /api/goodvibes-agent/knowledge/connectors/{id}',
+  ].filter((line): line is string => Boolean(line)).join('\n');
+}
+
+export function formatConnectorDoctor(data: unknown, id: string): string {
+  const record = isRecord(data) ? data : {};
+  const ready = readBoolean(record, 'ready');
+  const summary = cleanInline(record.summary);
+  const checks = readArray(record, 'checks');
+  const hints = readArray(record, 'hints').map(cleanInline).filter(Boolean);
+  return [
+    `Agent Knowledge connector doctor: ${cleanInline(record.connectorId) || id}`,
+    `  ready: ${ready === null ? 'unknown' : yesNo(ready)}`,
+    summary ? `  summary: ${summary}` : null,
+    checks.length > 0 ? '  checks:' : null,
+    ...checks.slice(0, 10).map((check) => {
+      const item = isRecord(check) ? check : {};
+      const checkId = cleanInline(item.id) || 'check';
+      const status = cleanInline(item.status) || 'unknown';
+      const label = cleanInline(item.label);
+      const detail = cleanInline(item.detail);
+      return `    - ${checkId} [${status}] ${label}${detail ? ` - ${detail}` : ''}`;
+    }),
+    hints.length > 0 ? '  hints:' : null,
+    ...hints.slice(0, 8).map((hint) => `    - ${hint}`),
+    '  route: /api/goodvibes-agent/knowledge/connectors/{id}/doctor',
+  ].filter((line): line is string => Boolean(line)).join('\n');
+}
+
 export function formatAsk(data: unknown, query: string): string {
   const record = isRecord(data) ? data : {};
   const answer = isRecord(record.answer) ? record.answer : record;
@@ -261,18 +306,24 @@ export function formatSearch(data: unknown, query: string): string {
   ].join('\n');
 }
 
-export function formatIngest(data: unknown, url: string): string {
+export function formatIngest(
+  data: unknown,
+  target: string,
+  label = 'ingest-url',
+  route = '/api/goodvibes-agent/knowledge/ingest/url',
+  targetLabel = 'url',
+): string {
   const record = isRecord(data) ? data : {};
   const source = isRecord(record.source) ? record.source : record;
   const sourceId = cleanInline(source.id);
-  const canonicalUri = cleanInline(source.canonicalUri) || cleanInline(source.sourceUri) || url;
+  const canonicalUri = cleanInline(source.canonicalUri) || cleanInline(source.sourceUri) || target;
   const artifactId = cleanInline(record.artifactId);
   return [
-    'Agent Knowledge ingest-url accepted',
+    `Agent Knowledge ${label} accepted`,
     `  source: ${sourceId || '(pending)'}`,
-    `  url: ${canonicalUri}`,
+    `  ${targetLabel}: ${canonicalUri}`,
     artifactId ? `  artifact: ${artifactId}` : null,
-    '  route: /api/goodvibes-agent/knowledge/ingest/url',
+    `  route: ${route}`,
   ].filter((line): line is string => Boolean(line)).join('\n');
 }
 
@@ -316,10 +367,10 @@ export function formatFailure(failure: AgentKnowledgeFailureLike, json: boolean)
       ? `  versions: runtime=${failure.daemonVersion} expected=${failure.expectedSdkVersion}`
       : null,
     failure.kind === 'version_mismatch'
-      ? '  next: update/restart the external GoodVibes runtime so /status matches the Agent SDK pin.'
+      ? '  next: update connected GoodVibes services so /status matches the Agent SDK pin.'
       : null,
     failure.kind === 'daemon_route_unavailable'
-      ? '  next: update/restart the external GoodVibes runtime to the SDK version required by this Agent package.'
+      ? '  next: update connected GoodVibes services to the SDK version required by this Agent package.'
       : null,
   ].filter((line): line is string => Boolean(line)).join('\n');
 }

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

@@ -0,0 +1,84 @@
+export interface DaemonCallMethod {
+  readonly kind: string;
+  readonly route: string;
+}
+
+export const AGENT_KNOWLEDGE_METHODS = {
+  status: {
+    kind: 'agentKnowledge.status',
+    route: '/api/goodvibes-agent/knowledge/status',
+  },
+  ask: {
+    kind: 'agentKnowledge.ask',
+    route: '/api/goodvibes-agent/knowledge/ask',
+  },
+  search: {
+    kind: 'agentKnowledge.search',
+    route: '/api/goodvibes-agent/knowledge/search',
+  },
+  sourcesList: {
+    kind: 'agentKnowledge.sources.list',
+    route: '/api/goodvibes-agent/knowledge/sources',
+  },
+  nodesList: {
+    kind: 'agentKnowledge.nodes.list',
+    route: '/api/goodvibes-agent/knowledge/nodes',
+  },
+  issuesList: {
+    kind: 'agentKnowledge.issues.list',
+    route: '/api/goodvibes-agent/knowledge/issues',
+  },
+  itemGet: {
+    kind: 'agentKnowledge.item.get',
+    route: '/api/goodvibes-agent/knowledge/items/{id}',
+  },
+  map: {
+    kind: 'agentKnowledge.map',
+    route: '/api/goodvibes-agent/knowledge/map',
+  },
+  connectorsList: {
+    kind: 'agentKnowledge.connectors.list',
+    route: '/api/goodvibes-agent/knowledge/connectors',
+  },
+  connectorGet: {
+    kind: 'agentKnowledge.connector.get',
+    route: '/api/goodvibes-agent/knowledge/connectors/{id}',
+  },
+  connectorDoctor: {
+    kind: 'agentKnowledge.connector.doctor',
+    route: '/api/goodvibes-agent/knowledge/connectors/{id}/doctor',
+  },
+  ingestUrl: {
+    kind: 'agentKnowledge.ingest.url',
+    route: '/api/goodvibes-agent/knowledge/ingest/url',
+  },
+  ingestArtifact: {
+    kind: 'agentKnowledge.ingest.artifact',
+    route: '/api/goodvibes-agent/knowledge/ingest/artifact',
+  },
+  ingestUrls: {
+    kind: 'agentKnowledge.ingest.urls',
+    route: '/api/goodvibes-agent/knowledge/ingest/urls',
+  },
+  ingestBookmarks: {
+    kind: 'agentKnowledge.ingest.bookmarks',
+    route: '/api/goodvibes-agent/knowledge/ingest/bookmarks',
+  },
+  ingestBrowserHistory: {
+    kind: 'agentKnowledge.ingest.browserHistory',
+    route: '/api/goodvibes-agent/knowledge/ingest/browser-history',
+  },
+  ingestConnector: {
+    kind: 'agentKnowledge.ingest.connector',
+    route: '/api/goodvibes-agent/knowledge/ingest/connector',
+  },
+  reindex: {
+    kind: 'agentKnowledge.reindex',
+    route: '/api/goodvibes-agent/knowledge/reindex',
+  },
+} as const;
+
+export const DELEGATION_METHOD = {
+  kind: 'sessions.messages.create',
+  route: 'sessions.messages.create',
+} as const;

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

@@ -0,0 +1,240 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createBrowserAgentSdk } from '@pellux/goodvibes-sdk/browser/agent';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+import { SDK_VERSION, VERSION } from '../version.ts';
+import type { CliCommandRuntime } from './management.ts';
+import type { DaemonCallMethod } from './agent-knowledge-methods.ts';
+
+export type JsonRecord = Record<string, unknown>;
+
+export interface AgentDaemonConnection {
+  readonly baseUrl: string;
+  readonly token: string | null;
+  readonly tokenPath: string;
+}
+
+export interface AgentKnowledgeFailure {
+  readonly ok: false;
+  readonly kind: 'daemon_unavailable' | 'auth_required' | 'version_mismatch' | 'daemon_route_unavailable' | 'daemon_error';
+  readonly error: string;
+  readonly baseUrl: string;
+  readonly route: string;
+  readonly daemonVersion?: string;
+  readonly expectedSdkVersion?: string;
+}
+
+export interface AgentKnowledgeSuccess<TData> {
+  readonly ok: true;
+  readonly kind: string;
+  readonly route: string;
+  readonly data: TData;
+}
+
+export type AgentKnowledgeResult<TData> = AgentKnowledgeSuccess<TData> | AgentKnowledgeFailure;
+
+export function isRecord(value: unknown): value is JsonRecord {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function readString(record: JsonRecord | null, key: string): string | null {
+  const value = record?.[key];
+  return typeof value === 'string' ? value : null;
+}
+
+export function readPackageMetadata(): { readonly version: string; readonly sdkVersion: string } {
+  return { version: VERSION, sdkVersion: SDK_VERSION };
+}
+
+export function resolveDaemonConnection(runtime: CliCommandRuntime): AgentDaemonConnection {
+  const host = String(runtime.configManager.get('controlPlane.host') ?? '127.0.0.1');
+  const port = Number(runtime.configManager.get('controlPlane.port') ?? 3421);
+  const baseUrl = `http://${host}:${Number.isFinite(port) ? port : 3421}`;
+  const tokenPath = join(runtime.homeDirectory, '.goodvibes', 'daemon', 'operator-tokens.json');
+  if (!existsSync(tokenPath)) return { baseUrl, token: null, tokenPath };
+  try {
+    const parsed = JSON.parse(readFileSync(tokenPath, 'utf-8')) as unknown;
+    const token = isRecord(parsed) && typeof parsed.token === 'string' ? parsed.token : null;
+    return { baseUrl, token, tokenPath };
+  } catch {
+    return { baseUrl, token: null, tokenPath };
+  }
+}
+
+export async function fetchDaemonStatus(connection: AgentDaemonConnection): Promise<{ readonly ok: boolean; readonly status: number; readonly body: unknown }> {
+  try {
+    const response = await fetch(`${connection.baseUrl}/status`, {
+      headers: connection.token ? { authorization: `Bearer ${connection.token}` } : undefined,
+    });
+    const text = await response.text();
+    let body: unknown = text;
+    try {
+      body = JSON.parse(text) as unknown;
+    } catch {
+      body = text;
+    }
+    return { ok: response.ok, status: response.status, body };
+  } catch (error) {
+    return { ok: false, status: 0, body: summarizeError(error) };
+  }
+}
+
+export async function classifyKnowledgeError(error: unknown, connection: AgentDaemonConnection, route: string): Promise<AgentKnowledgeFailure> {
+  const message = summarizeError(error);
+  const lower = message.toLowerCase();
+  if (lower.includes('401') || lower.includes('unauthorized') || lower.includes('auth')) {
+    return { ok: false, kind: 'auth_required', error: message, baseUrl: connection.baseUrl, route };
+  }
+  if (lower.includes('404') || lower.includes('not found')) {
+    const metadata = readPackageMetadata();
+    const daemon = await fetchDaemonStatus(connection);
+    const daemonRecord = isRecord(daemon.body) ? daemon.body : {};
+    const daemonVersion = readString(daemonRecord, 'version') ?? 'unknown';
+    if (daemon.ok && daemonVersion !== metadata.sdkVersion) {
+      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.`,
+        baseUrl: connection.baseUrl,
+        route,
+        daemonVersion,
+        expectedSdkVersion: metadata.sdkVersion,
+      };
+    }
+    return { ok: false, kind: 'daemon_route_unavailable', error: message, baseUrl: connection.baseUrl, route };
+  }
+  if (lower.includes('fetch') || lower.includes('connect') || lower.includes('econnrefused')) {
+    return { ok: false, kind: 'daemon_unavailable', error: message, baseUrl: connection.baseUrl, route };
+  }
+  return { ok: false, kind: 'daemon_error', error: message, baseUrl: connection.baseUrl, route };
+}
+
+export function createAgentSdk(connection: AgentDaemonConnection) {
+  return createBrowserAgentSdk({
+    baseUrl: connection.baseUrl,
+    authToken: connection.token,
+  });
+}
+
+export async function postAgentKnowledgeJson<TData>(
+  connection: AgentDaemonConnection,
+  route: string,
+  body: JsonRecord,
+): Promise<TData> {
+  const response = await fetch(`${connection.baseUrl}${route}`, {
+    method: 'POST',
+    headers: {
+      authorization: `Bearer ${connection.token ?? ''}`,
+      'content-type': 'application/json',
+    },
+    body: JSON.stringify(body),
+  });
+  const text = await response.text();
+  let parsed: unknown = text;
+  if (text.trim()) {
+    try {
+      parsed = JSON.parse(text) as unknown;
+    } catch {
+      parsed = text;
+    }
+  }
+  if (!response.ok) {
+    const detail = isRecord(parsed) && typeof parsed.error === 'string' ? parsed.error : text;
+    throw new Error(`HTTP ${response.status} ${response.statusText}${detail ? `: ${detail}` : ''}`);
+  }
+  return parsed as TData;
+}
+
+function queryRoute(route: string, query: JsonRecord): string {
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value === undefined || value === null || value === '') continue;
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        if (typeof item === 'string' && item.trim().length > 0) params.append(key, item);
+      }
+      continue;
+    }
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+      params.set(key, String(value));
+    }
+  }
+  const suffix = params.toString();
+  return suffix ? `${route}?${suffix}` : route;
+}
+
+export async function getAgentKnowledgeJson<TData>(
+  connection: AgentDaemonConnection,
+  route: string,
+  query: JsonRecord = {},
+): Promise<TData> {
+  const response = await fetch(`${connection.baseUrl}${queryRoute(route, query)}`, {
+    headers: {
+      authorization: `Bearer ${connection.token ?? ''}`,
+    },
+  });
+  const text = await response.text();
+  let parsed: unknown = text;
+  if (text.trim()) {
+    try {
+      parsed = JSON.parse(text) as unknown;
+    } catch {
+      parsed = text;
+    }
+  }
+  if (!response.ok) {
+    const detail = isRecord(parsed) && typeof parsed.error === 'string' ? parsed.error : text;
+    throw new Error(`HTTP ${response.status} ${response.statusText}${detail ? `: ${detail}` : ''}`);
+  }
+  return parsed as TData;
+}
+
+export function findDisallowedKnowledgeScopeFlag(args: readonly string[]): string | null {
+  const disallowed = [
+    '--space',
+    '--knowledge-space',
+    '--knowledge-space-id',
+    ['--knowledge', 'SpaceId'].join(''),
+    '--include-all-spaces',
+    ['--include', 'AllSpaces'].join(''),
+    ['--home', 'graph'].join(''),
+    ['--home', '-graph'].join(''),
+  ];
+  for (const token of args) {
+    for (const flag of disallowed) {
+      if (token === flag || token.startsWith(`${flag}=`)) return flag;
+    }
+  }
+  return null;
+}
+
+export function formatScopeFlagRejection(flag: string): string {
+  return [
+    `Agent Knowledge is isolated; ${flag} is not accepted.`,
+    'GoodVibes Agent must not use default Knowledge/Wiki or non-Agent product spaces.',
+    'Use only /api/goodvibes-agent/knowledge/* Agent-owned routes.',
+  ].join('\n');
+}
+
+export async function runKnowledgeCall<TData>(
+  runtime: CliCommandRuntime,
+  method: DaemonCallMethod,
+  call: (connection: AgentDaemonConnection) => Promise<TData>,
+): Promise<AgentKnowledgeResult<TData>> {
+  const connection = resolveDaemonConnection(runtime);
+  if (!connection.token) {
+    return {
+      ok: false,
+      kind: 'auth_required',
+      error: `No runtime operator token found at ${connection.tokenPath}`,
+      baseUrl: connection.baseUrl,
+      route: method.route,
+    };
+  }
+  try {
+    const data = await call(connection);
+    return { ok: true, kind: method.kind, route: method.route, data };
+  } catch (error) {
+    return classifyKnowledgeError(error, connection, method.route);
+  }
+}

package/src/cli/config-overrides.ts

@@ -36,13 +36,13 @@ function parseRuntimeUrl(rawValue: string, source: string): { readonly host: str
   }
 
   if (url.protocol !== 'http:') {
-    throw new ConfigError(`${source} must use http:// because Agent connects to the local GoodVibes runtime API.`);
+    throw new ConfigError(`${source} must use http:// because Agent connects to the local GoodVibes API.`);
   }
   if (!url.hostname) {
     throw new ConfigError(`${source} must include a hostname.`);
   }
   if ((url.pathname && url.pathname !== '/') || url.search || url.hash) {
-    throw new ConfigError(`${source} must point at the runtime root, not a path, query, or hash.`);
+    throw new ConfigError(`${source} must point at the connected GoodVibes API root, not a path, query, or hash.`);
   }
 
   const port = url.port ? Number.parseInt(url.port, 10) : 3421;

package/src/cli/help.ts

@@ -27,6 +27,20 @@ export function renderGoodVibesHelp(binary = 'goodvibes-agent'): string {
   return [
     `Usage: ${binary} [OPTIONS] [PROMPT]`,
     `       ${binary} [OPTIONS] <COMMAND> [ARGS]`,
+    '',
+    'Primary use:',
+    `  ${binary}                 Launch the interactive Agent TUI`,
+    `  ${binary} setup           Open first-run Agent setup`,
+    '',
+    'Inside the TUI:',
+    '  /agent                    Open the operator workspace',
+    '  /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',
     '',
     'Commands:',
     '  tui [path]                 Start the interactive Agent terminal UI (default)',
@@ -40,9 +54,9 @@ export function renderGoodVibesHelp(binary = 'goodvibes-agent'): string {
     '  personas                   Manage local Agent personas',
     '  skills                     Manage local Agent skills and skill bundles',
     '  memory                     Manage Agent-owned durable memory records',
-    '  routines                   Inspect local routines and explicitly promote one to an external schedule',
-    '  auth                       Inspect Agent auth posture and external runtime token state',
-    '  compat                     Inspect Agent SDK pin, runtime version, and Agent knowledge route readiness',
+    '  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',
     '  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',
@@ -60,7 +74,7 @@ export function renderGoodVibesHelp(binary = 'goodvibes-agent'): string {
     '  -m, --model <registryKey>       Override model. provider:model infers --provider',
     '      --provider <id>            Override provider',
     '      --agent-profile <name>     Use an isolated Agent profile home',
-    '      --runtime-url <url>        External GoodVibes runtime API root',
+    '      --runtime-url <url>        Connected GoodVibes API root',
     '  -C, --cd <dir>                 Set working directory for this launch',
     '      --working-dir <dir>        Alias for --cd',
     '  -c, --config <key=value>       Override a config value for this launch',
@@ -135,7 +149,7 @@ const COMMAND_HELP: Record<string, CommandHelp> = {
   },
   status: {
     usage: ['status', 'status --json', '--runtime-url http://127.0.0.1:3421 status'],
-    summary: 'Print Agent config, provider, auth, runtime connection, and setup posture.',
+    summary: 'Print Agent config, provider, auth, connected-service state, and setup posture.',
     examples: ['status', 'status --json', '--runtime-url http://127.0.0.1:3421 status'],
   },
   doctor: {
@@ -150,7 +164,7 @@ const COMMAND_HELP: Record<string, CommandHelp> = {
   },
   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 the shared GoodVibes runtime.',
+    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'],
   },
   personas: {
@@ -237,7 +251,7 @@ const COMMAND_HELP: Record<string, CommandHelp> = {
       '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 Agent-local routines, review local promotion receipts, reconcile receipts against live external schedules, and explicitly promote a reviewed routine into a GoodVibes schedule. Without --yes, promote only prints the schedules.create preview.',
+    summary: 'Inspect 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.',
     examples: [
       'routines list',
       'routines show daily-operations-sweep',
@@ -254,7 +268,7 @@ const COMMAND_HELP: Record<string, CommandHelp> = {
   },
   auth: {
     usage: ['auth', 'auth status', 'auth review', 'auth users', 'auth sessions'],
-    summary: 'Inspect Agent auth posture and external runtime token state. Runtime user/session administration belongs to the runtime-owning TUI or host tooling.',
+    summary: 'Inspect Agent auth posture and connection token state. Runtime user/session administration stays outside Agent.',
     examples: ['auth', 'auth status', 'auth users'],
   },
   compat: {
@@ -269,10 +283,13 @@ const COMMAND_HELP: Record<string, CommandHelp> = {
       'knowledge search <query> [--limit <n>]',
       'knowledge list [--kind sources|nodes|issues] [--limit <n>]',
       'knowledge get <id>',
-      'knowledge connectors',
+      'knowledge connectors [connectorId|doctor <connectorId>]',
       'knowledge ingest-url <url> [--title <title>] [--tags a,b] --yes',
+      'knowledge ingest-file <path> [--title <title>] [--tags a,b] --yes',
+      'knowledge ingest-connector <connectorId> [--input <json-or-text>|--path <path>|--content <text>] --yes',
       'knowledge import-urls <path> --yes',
       'knowledge import-bookmarks <path> --yes',
+      'knowledge import-browser-history [--browsers chrome,firefox] [--sources history,bookmark] --yes',
       'knowledge reindex --yes',
     ],
     summary: 'Call isolated Agent Knowledge/Wiki routes under /api/goodvibes-agent/knowledge. No default wiki or non-Agent fallback.',
@@ -282,8 +299,12 @@ const COMMAND_HELP: Record<string, CommandHelp> = {
       'knowledge search "release checklist"',
       'knowledge list --kind sources',
       'knowledge connectors',
+      'knowledge connectors doctor url',
       'knowledge ingest-url https://example.com/page --title "Reference" --yes',
+      'knowledge ingest-file ./docs/guide.md --title "Guide" --yes',
+      'knowledge ingest-connector url --input https://example.com/reference --yes',
       'knowledge import-urls ~/agent-links.txt --yes',
+      'knowledge import-browser-history --browsers chrome,firefox --sources history,bookmark --yes',
     ],
   },
   ask: {
@@ -321,7 +342,7 @@ const COMMAND_HELP: Record<string, CommandHelp> = {
   },
   tasks: {
     usage: ['tasks list', 'tasks show <taskId>'],
-    summary: 'Inspect in-process runtime tasks. Agent blocks runtime-owned task submission; use run for one-shot work or delegate for explicit build/fix/review handoff.',
+    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.',
     examples: ['tasks list', 'tasks show task-123', 'run "check provider readiness"', 'delegate "fix the failing tests"'],
   },
   bundle: {
@@ -342,7 +363,6 @@ const COMMAND_HELP: Record<string, CommandHelp> = {
 };
 
 const HELP_ALIASES: Record<string, string> = {
-  app: 'tui',
   exec: 'run',
   onboarding: 'setup',
   provider: 'providers',

package/src/cli/management-commands.ts

@@ -279,7 +279,7 @@ export async function handleTasks(runtime: CliCommandRuntime): Promise<string> {
   const [sub = 'list', ...rest] = runtime.cli.commandArgs;
   if (sub === 'submit') {
     return [
-      'GoodVibes Agent blocks CLI task submission from the runtime-owned task workflow.',
+      'GoodVibes Agent blocks CLI task submission from the service-owned task workflow.',
       '  policy: do normal assistant work in the main Agent conversation or use `goodvibes-agent run <prompt>` for an explicit one-shot run.',
       '  build/fix/review: use `goodvibes-agent delegate <task>` for explicit GoodVibes TUI handoff.',
       '  result: no local task was started.',
@@ -289,7 +289,7 @@ export async function handleTasks(runtime: CliCommandRuntime): Promise<string> {
     const tasks = [...services.runtimeStore.getState().tasks.tasks.values()];
     if (sub === 'list') {
       return tasks.length === 0
-        ? 'GoodVibes tasks\n  No in-process runtime tasks are currently recorded.'
+        ? 'GoodVibes tasks\n  No connected-service tasks are currently recorded.'
         : ['GoodVibes tasks', ...tasks.map((task) => `  ${task.id} ${task.status} ${task.kind} ${task.title}`)].join('\n');
     }
     if (sub === 'show') {

package/src/cli/management.ts

@@ -544,9 +544,9 @@ async function renderAuth(runtime: CliCommandRuntime): Promise<string> {
   ]);
   if (blocked.has(sub)) {
     return [
-      'Unsupported: runtime auth user/session administration is external to GoodVibes Agent.',
-      'GoodVibes Agent connects to an already-running runtime and does not create, delete, rotate, revoke, or clear runtime users, sessions, or bootstrap credentials.',
-      'Use the runtime-owning GoodVibes TUI or host tooling for runtime auth administration.',
+      'Unsupported: connected-service auth user/session administration is outside GoodVibes Agent.',
+      'GoodVibes Agent does not create, delete, rotate, revoke, or clear connected-service users, sessions, or bootstrap credentials.',
+      'Use the owning GoodVibes host for auth administration.',
     ].join('\n');
   }
   if (sub !== 'status' && sub !== 'review' && sub !== 'list' && sub !== 'users' && sub !== 'sessions') {
@@ -566,21 +566,21 @@ async function renderAuth(runtime: CliCommandRuntime): Promise<string> {
   if (sub === 'users' || sub === 'sessions') {
     return formatJsonOrText(runtime.cli)(value, [
       `GoodVibes Agent auth ${sub}`,
-      '  owner: external GoodVibes runtime',
+      '  owner: connected GoodVibes services',
       `  operator token: ${paths.operatorTokenPresent ? 'present' : 'missing'}`,
       `  operator token path: ${paths.operatorTokenPath}`,
-      `  ${sub}: managed by the runtime-owning TUI or host tooling`,
-      '  Agent does not enumerate or mutate runtime users/sessions from the local CLI.',
+      `  ${sub}: managed outside Agent`,
+      '  Agent does not enumerate or mutate connected-service users/sessions from the local CLI.',
     ].join('\n'));
   }
   return formatJsonOrText(runtime.cli)(value, [
     'GoodVibes Agent auth',
-    '  owner: external GoodVibes runtime',
+    '  owner: connected GoodVibes services',
     `  permission mode: ${String(value.permissionMode)}`,
     `  operator token: ${paths.operatorTokenPresent ? 'present' : 'missing'} (${paths.operatorTokenPath})`,
     `  compatibility user store: ${paths.userStorePresent ? 'present' : 'missing'} (${paths.userStorePath})`,
     `  compatibility bootstrap credential: ${paths.bootstrapCredentialPresent ? 'present' : 'missing'} (${paths.bootstrapCredentialPath})`,
-    '  runtime user/session administration: external',
+    '  connected-service user/session administration: outside Agent',
     '  next: goodvibes-agent providers',
     '  next: goodvibes-agent subscription providers',
   ].join('\n'));

package/src/cli/package-verification.ts

@@ -41,7 +41,7 @@ const REQUIRED_TARBALL_PATHS = [
   'tsconfig.json',
   'docs/README.md',
   'docs/getting-started.md',
-  'docs/runtime-connection.md',
+  'docs/connected-services.md',
   'docs/release-and-publishing.md',
 ] as const;
 const FORBIDDEN_TARBALL_PREFIXES = ['.github/', 'src/test/', 'src/.test/', '.goodvibes/', 'vendor/'] as const;
@@ -64,7 +64,7 @@ const PACKAGE_FACING_TEXT_PATHS = [
   'CHANGELOG.md',
   'docs/README.md',
   'docs/getting-started.md',
-  'docs/runtime-connection.md',
+  'docs/connected-services.md',
   'docs/release-and-publishing.md',
 ] as const;
 const PACKAGE_FACING_FORBIDDEN_TEXT = [
@@ -101,6 +101,10 @@ const PACKAGE_FACING_FORBIDDEN_TEXT = [
   ['goodvibes-agent', 'remote'].join(' '),
   ['goodvibes-agent', 'bridge'].join(' '),
   ['goodvibes-agent', 'web'].join(' '),
+  ['goodvibes-agent', 'launch'].join(' '),
+  ['goodvibes-agent', 'start'].join(' '),
+  ['tui', '|launch'].join(''),
+  ['tui', '|launch|start'].join(''),
   'Every plan must have a multi-agent execution strategy',
   'NEVER skip WRFC',
   'ALWAYS work in parallel when implementing a plan',
@@ -116,7 +120,7 @@ const PACKAGE_FACING_REQUIRED_TEXT: readonly {
   { path: 'README.md', required: ['/api/goodvibes-agent/knowledge', 'bun add -g --trust @pellux/goodvibes-agent', 'bun pm -g untrusted'] },
   { path: 'docs/README.md', required: ['/api/goodvibes-agent/knowledge'] },
   { path: 'docs/getting-started.md', required: ['/api/goodvibes-agent/knowledge', 'bun add -g --trust @pellux/goodvibes-agent', 'bun pm -g untrusted'] },
-  { path: 'docs/runtime-connection.md', required: ['/api/goodvibes-agent/knowledge'] },
+  { path: 'docs/connected-services.md', required: ['/api/goodvibes-agent/knowledge'] },
   { path: 'docs/release-and-publishing.md', required: ['/api/goodvibes-agent/knowledge', 'bun add -g --trust @pellux/goodvibes-agent', 'bun pm -g untrusted'] },
 ];
 const NON_COMMAND_ROUTE_ROOTS = new Set(['api', 'status']);