@pellux/goodvibes-agent 0.1.116 → 1.0.0

package/README.md

@@ -5,9 +5,9 @@
 
 GoodVibes Agent is the personal operator assistant TUI for GoodVibes. It is built for day-to-day operator work: chat, setup, local profiles, routines, skills, personas, isolated Agent Knowledge, status review, approvals, automation visibility, and explicit build delegation.
 
-The Agent product connects to GoodVibes services owned outside this package. It does not install, start, stop, restart, or own those services.
+The Agent product connects to a GoodVibes host owned outside this package. It does not install, start, stop, restart, or own that host.
 
-Most work happens in the interactive TUI. The installed CLI exists to launch that TUI, inspect setup, and script local Agent libraries when that is useful.
+Most work happens in the interactive TUI. The installed CLI exists to launch that TUI and provide scriptable mirrors for workflows that are already reachable from the workspace.
 
 ## Install
 
@@ -17,14 +17,6 @@ Install the public alpha package with Bun:
 bun add -g @pellux/goodvibes-agent
 goodvibes-agent --help
 goodvibes-agent
-goodvibes-agent status
-goodvibes-agent profiles templates
-goodvibes-agent personas list
-goodvibes-agent skills list
-goodvibes-agent memory list
-goodvibes-agent knowledge status
-goodvibes-agent knowledge list --kind sources
-goodvibes-agent knowledge import-urls ./agent-sources.txt --yes
 ```
 
 If `goodvibes-agent` is not found after installation, add Bun's global bin directory to `PATH`:
@@ -54,79 +46,94 @@ bun run package:install-check
 bun run publish:check
 ```
 
-After setup has been shown once, the Agent TUI opens directly into the operator workspace. You can also reopen it with `/agent`, `/home`, or `/operator`. It is the Agent-first fullscreen workspace for setup, model/provider selection, isolated Agent Knowledge, local memory/skills/routines/personas, channel readiness, voice/media setup, work-plan/approval review, automation observability, and explicit build delegation to GoodVibes TUI.
+After setup has been applied once, the Agent TUI opens directly into the operator workspace. You can also reopen it with `/agent`, `/home`, or `/operator`. It is the Agent-first fullscreen workspace for setup, conversation/session controls, model/provider selection, isolated Agent Knowledge, local memory/notes/skills/routines/personas, channel readiness, voice/media setup, work-plan/approval review, automation observability, and explicit build delegation to GoodVibes TUI.
 
-The setup workspace surfaces discovered local Agent persona, skill, and routine markdown files so day-one setup can import useful behavior instead of starting from blank records.
+Use the workspace as the primary product surface:
 
-Inside the workspace, use `/agent-profile guide` to author custom profile starters without leaving the Agent TUI. The guided flow lists starters, exports starter JSON, imports edited local starters, and creates isolated Agent profiles from them.
+- Home: normal assistant chat, operator briefing, model selection, setup, and health.
+- Conversation: context usage, inline `@file`/`@folder`/`@url` references, compaction, title/session save/load/search/export, transcript search, bookmarks, paste/image/TTS helpers, undo/redo/retry, clear/reset, shortcuts, and keybindings.
+- Research: read-only web research, URL inspection, source triage, and explicit handoff into isolated Agent Knowledge when a source should become durable.
+- Artifacts: image attachment, conversation/session export, source-file ingest, source lookup, bookmark/browser-history import, and generated media artifact handling.
+- Setup: provider/model, compatibility, Agent Knowledge readiness, profiles, support bundles, subscriptions, and auth review.
+- Tools & MCP: MCP server setup, tool inventory, trust review, secret storage/link/test/delete, and settings.
+- Knowledge: isolated Agent Knowledge status, ask/search, URL/URL-list/file/bookmark/browser-history/connector ingest, source library, review queue, and reindex.
+- Memory & Skills: local memory, scratchpad notes, learned behavior capture, personas, skills, routines, and schedule promotion.
+- Notes: Agent-local scratchpad for source triage, temporary decisions, and operator handoff. Notes do not become memory or Agent Knowledge unless you explicitly promote or ingest something; reviewed notes can prefill memory, skills, routines, personas, or an isolated Agent Knowledge URL ingest.
+- Channels: companion pairing, channel readiness, confirmed channel delivery, and confirmed webhook add/remove/test/send.
+- Voice & Media: voice review, spoken response setup, image input, confirmed image/video generation, browser-tool posture, MCP inventory, and media provider readiness.
+- Automation: reminder creation, schedule status, routine promotion, receipts, reconciliation, and explicitly confirmed approve/deny/cancel/run/pause/resume/retry actions.
+- Build Delegation: explicit handoff to GoodVibes TUI for build/fix/review work.
 
-Use `profiles create-from-discovered <name> --yes` or the Profiles workspace form to turn reviewed discovered persona, skill, and routine files into a local starter template and isolated Agent profile in one confirmed flow. `profiles templates from-discovered <id> --yes` is still available when you only want to save the starter first.
+Inside the Agent workspace, press `/` to search every workspace action by name, category, command, or detail. This is the primary discovery path for product actions; slash commands and CLI subcommands remain power-user/scriptable mirrors.
+
+The setup workspace surfaces discovered Agent-local persona, skill, and routine markdown files so day-one setup can import useful behavior instead of starting from blank records. It can also create one initial scratchpad note, local persona, skill, and routine directly during first-run setup; those records stay in Agent-local registries and never write to default knowledge or non-Agent segments.
+
+In the Profiles workspace, choose Starter authoring guide to author custom profile starters without leaving the Agent TUI. The guided flow lists starters, exports starter JSON, imports edited local starters, and creates isolated Agent profiles from them.
+
+Use the Profiles workspace form to turn reviewed discovered persona, skill, and routine files into a local starter template and isolated Agent profile in one confirmed flow. The scriptable equivalent is `profiles create-from-discovered <name> --yes`; `profiles templates from-discovered <id> --yes` is still available when you only want to save the starter first.
 
 The Knowledge area includes an in-workspace URL ingest form. It writes only to Agent Knowledge, requires typed confirmation, and dispatches the existing isolated `/knowledge ingest-url ... --yes` route.
 
-Use isolated Agent profiles when one machine needs separate operator identities or local state:
+The Research workspace submits web research and URL inspection requests back to the normal Agent conversation. These requests can use connected read-only web tools when the user asks, but they do not ingest sources into Agent Knowledge. Use the separate confirmed Agent Knowledge ingest actions when a reviewed source should become durable.
 
-```sh
-goodvibes-agent profiles templates
-goodvibes-agent profiles create household --template household --yes
-goodvibes-agent personas create --name "Travel Planner" --description "Plan trips" --body "Compare options before booking" --use
-goodvibes-agent skills create --name "Daily Brief" --description "Summarize operator state" --procedure "Review Agent Knowledge, work plans, approvals, and routines" --enabled
-goodvibes-agent memory add fact "Prefers concise morning briefings" --scope project --tags preference
-goodvibes-agent profiles templates export research ./research-starter.json --yes
-goodvibes-agent profiles templates import ./research-starter.json --yes
-goodvibes-agent --agent-profile household status
-GOODVIBES_AGENT_HOME=/path/to/agent-home goodvibes-agent status
-```
+The Voice & Media workspace includes `Generate media`, a confirmed form for image/video generation through configured media providers. Generated bytes are stored as GoodVibes artifacts and the transcript shows artifact ids, not inline base64. The power-user mirror is `/media generate [--provider <id>] [--model <id>] [--mime <mime>] <prompt> --yes`; `/media providers` lists readiness.
 
-Profiles isolate Agent-local config, sessions, local memory, personas, skills, routines, and setup state. Starter templates seed local personas, skills, and routines for household, research, travel, operations, and personal productivity profiles; exported starter JSON can be edited and re-imported as a local starter. Connected GoodVibes services remain shared unless the owning host is separately configured otherwise.
-
-The same local behavior libraries are available without opening the TUI: `goodvibes-agent personas ...`, `goodvibes-agent skills ...`, `goodvibes-agent memory ...`, and `goodvibes-agent routines ...` list, create, review, enable, stale, export/import where relevant, and delete local Agent records with explicit confirmation for destructive actions.
-
-Local Agent behavior is editable from the TUI:
-
-```text
-/personas create --name Research --description "Source-backed research" --body "Check sources, call out uncertainty, keep answers concise."
-/personas use research
-/routines create --name "Evening Review" --description "Review open work before shutdown" --steps "Check work plan, approvals, and Agent Knowledge status before summarizing." --enabled true
-/routines start evening-review
-/schedule promote-routine evening-review --cron "0 17 * * 1-5" --timezone America/Chicago --delivery-channel slack --yes
-/schedule receipts
-/schedule reconcile
-/channels
-/agent-skills create --name "Morning Brief" --description "Daily briefing flow" --procedure "Check tasks, approvals, calendar, and unread state before summarizing." --enabled true
-/skills list
-/memory add fact "Prefers concise morning briefings" --scope project --tags preference
-/memory search morning
-```
+Use isolated Agent profiles when one machine needs separate operator identities or local state. In the TUI, open Agent Workspace -> Profiles to browse starters, create a profile, use it as the default for the next launch, clear the default, and export/import starter JSON. The same profile selection is available for one launch with `goodvibes-agent --agent-profile <name>`.
+
+Profiles isolate Agent-local config, sessions, local memory, scratchpad notes, personas, skills, routines, and setup state. First-run setup seeds new profiles from a built-in starter by default unless you explicitly choose `No profile`. Starter templates seed local personas, skills, and routines for household, research, travel, operations, and personal productivity profiles; exported starter JSON can be edited and re-imported as a local starter. The connected GoodVibes host remains shared unless that host is separately configured otherwise.
+
+The installed CLI mirrors the same local behavior libraries for scripts and automation, but it is not the primary product path. Personas, skills, memory, and routines are created, reviewed, enabled, exported/imported where relevant, and deleted from the TUI workspace first; destructive actions still require explicit confirmation.
+
+The Agent workspace also has a `Capture learned behavior` form. Use it after reviewing a repeated workflow, lesson, or operating style; it saves one local skill, routine, or persona directly from the TUI and does not write to connected-host routes or non-Agent knowledge.
+
+When the user explicitly asks, the main assistant conversation can perform the same narrow operator actions exposed by the TUI: approve/deny/cancel a named approval, run/pause/resume a named automation job, cancel/retry a named automation run, or run a named schedule. These actions require explicit confirmation, use only public connected-host operator routes, and do not create, edit, or delete automation definitions.
+
+Agent-local behavior is editable from the TUI workspace:
+
+- Agent Workspace -> Personas: create, inspect, activate, review, stale, and delete local personas.
+- Agent Workspace -> Skills: create skills, import discovered skills, enable or disable them, and manage skill bundles.
+- Agent Workspace -> Routines: create routines, start a routine in the main conversation, review receipts, and explicitly promote one routine to a connected schedule.
+- Agent Workspace -> Work: review the visible local work plan, add work items, and update status from the TUI while the main assistant conversation can keep the same plan current.
+- Agent Workspace -> Memory & Skills: create memory, search memory, review/stale/delete records, export/import bundles, and rebuild the local vector index.
+- Agent Workspace -> Notes: create, edit, review, stale, delete, and promote Agent-local scratchpad notes into memory, skills, routines, or personas.
+- Agent Workspace -> Channels: inspect readiness, pair companion clients, send one confirmed channel delivery message, and manage or send configured notification targets with confirmation.
+
+Slash commands remain available inside the TUI for power users, but the fullscreen Agent workspace is the primary path for these workflows.
 
-Starting a routine records local usage and prints its steps; it does not spawn background agents or automation jobs. Promotion to a connected schedule is separate and explicit: it calls the public `schedules.create` route only after `--yes`, can include explicit delivery targets such as `--delivery-channel slack`, records a redacted local receipt, and the generated scheduled prompt keeps Agent Knowledge isolated from default Knowledge/Wiki and non-Agent knowledge segments. Use `/schedule reconcile` to compare those local receipts against live connected schedules through public `schedules.list`.
+Starting a routine records local usage and prints its steps in the main conversation; it does not start background automation. Promotion to a connected schedule is separate and explicit: it calls the public `schedules.create` route only after `--yes`, can include explicit delivery targets such as `--delivery-channel slack`, records a redacted local receipt, and the generated scheduled prompt keeps Agent Knowledge isolated from default knowledge and non-Agent knowledge segments. Use `/schedule reconcile` to compare those local receipts against live connected schedules through public `schedules.list`.
 
-Use `/channels` inside the TUI for a read-only channel readiness matrix. It shows enabled channels, missing config key names, delivery posture, and risk labels without sending messages or rendering token values.
+Use `/channels` inside the TUI for channel readiness and exact confirmed sends. Readiness views show enabled channels, missing config key names, delivery posture, and risk labels without sending messages or rendering token values. Companion pairing is QR-first; `/pair` hides the raw token in text, and manual token display requires `/pair --show-token --yes`. `/channels send --channel <surface[:route[:label]]> --message <text> --yes` sends one explicit delivery through configured strategies.
 
-## Connected Services
+## Connected Host
 
-Start connected GoodVibes services from GoodVibes TUI or the owning host before launching Agent. Agent status and companion/knowledge routes normally connect on `http://127.0.0.1:3421`.
+Start the owning GoodVibes host before launching Agent. Agent status and companion/knowledge routes normally connect on `http://127.0.0.1:3421`.
 
-Use `--runtime-url http://host:port` for a one-off launch, or set `GOODVIBES_AGENT_RUNTIME_URL=http://host:port` when connected GoodVibes services are not on the default local port. The legacy `GOODVIBES_AGENT_BASE_URL` env var is also accepted as an alias. These only change the connection target; Agent still does not host or start services.
+Use `--runtime-url http://host:port` for a one-off launch, or set `GOODVIBES_AGENT_RUNTIME_URL=http://host:port` when the connected host is not on the default local port. The legacy `GOODVIBES_AGENT_BASE_URL` env var is also accepted as an alias. These only change the connection target; Agent still does not host or start it.
 
-Agent reports unavailable, unauthenticated, or incompatible connected-service state through `goodvibes-agent status`, `goodvibes-agent doctor`, and the TUI status views. Service lifecycle commands remain outside the Agent product.
+Agent reports unavailable, unauthenticated, or incompatible connected-host state from Agent Workspace -> Home through Host compatibility, Doctor diagnostics, and Review health. `goodvibes-agent status`, `goodvibes-agent doctor`, and `goodvibes-agent compat` are scriptable mirrors for install checks. Host lifecycle stays outside the Agent product.
 
 ## Product Boundary
 
-GoodVibes Agent owns the operator assistant TUI: serial assistant flow, proactive safe actions, local memory/routines/skills/personas, Agent knowledge routes, companion chat, approvals/automation observability, and explicit build delegation.
+GoodVibes Agent owns the operator assistant TUI: serial assistant flow, proactive safe actions, local memory/notes/routines/skills/personas, Agent knowledge routes, companion chat, approvals/automation observability, and explicit build delegation.
 
-Agent Knowledge/Wiki is its own product segment. Agent uses `/api/goodvibes-agent/knowledge/*` and must not fall back to default Knowledge/Wiki or other product-specific knowledge routes.
+Agent Knowledge is its own product segment. Agent uses `/api/goodvibes-agent/knowledge/*` and must not fall back to default knowledge or other product-specific knowledge routes.
 
-Agent Knowledge CLI commands can ask/search, inspect sources/nodes/issues, inspect connectors, ingest a URL, import URL/bookmark files, and reindex the Agent segment. Confirmed mutations require `--yes`.
+Agent Workspace -> Knowledge can ask/search, inspect sources/nodes/issues, inspect connectors, ingest URL/file/bookmark/browser-history/connector input, and reindex the Agent segment. CLI commands mirror those same isolated Agent Knowledge workflows for scripts. Confirmed mutations require explicit confirmation.
 
-GoodVibes TUI owns coding execution: file edits, git/worktree workflows, coding panels, execution isolation UX, and WRFC execution. Agent may delegate explicit build/fix/review work to TUI through public runtime/session contracts; normal assistant chat must not use shared coding sessions.
+GoodVibes TUI owns coding execution: file edits, git/worktree workflows, coding panels, execution isolation UX, and delegated review execution. Agent may delegate explicit build/fix/review work to TUI through public runtime/session contracts; normal assistant chat must not use shared coding sessions.
 
 ## Package Docs
 
 Package-facing docs:
 
 - [Getting Started](docs/getting-started.md)
-- [Connected Services](docs/connected-services.md)
+- [Connected Host](docs/connected-host.md)
+- [Knowledge, Artifacts, and Multimodal](docs/knowledge-artifacts-and-multimodal.md)
+- [Tools and Commands](docs/tools-and-commands.md)
+- [Channels, Remote Access, and API](docs/channels-remote-and-api.md)
+- [Providers and Routing](docs/providers-and-routing.md)
+- [Voice and Live TTS](docs/voice-and-live-tts.md)
+- [Project Planning](docs/project-planning.md)
 - [Release And Publishing](docs/release-and-publishing.md)
 
 The package-facing Agent documentation is limited to the docs listed above.

package/bin/goodvibes-agent.ts

@@ -6,8 +6,22 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 const runtimeEntry = join(dirname(fileURLToPath(import.meta.url)), '..', 'dist', 'package', 'main.js');
 
 if (!existsSync(runtimeEntry)) {
-  console.error('goodvibes-agent packaged runtime is missing. Reinstall @pellux/goodvibes-agent with Bun.');
+  console.error([
+    'goodvibes-agent packaged runtime is missing.',
+    'Reinstall with Bun: bun add -g @pellux/goodvibes-agent',
+    'If the command is not on PATH, add Bun global bin: export PATH="$HOME/.bun/bin:$PATH"',
+  ].join('\n'));
   process.exit(1);
 }
 
-await import(pathToFileURL(runtimeEntry).href);
+try {
+  await import(pathToFileURL(runtimeEntry).href);
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error([
+    `goodvibes-agent failed to launch the packaged runtime: ${message}`,
+    'Reinstall with Bun: bun add -g @pellux/goodvibes-agent',
+    'Then run: goodvibes-agent',
+  ].join('\n'));
+  process.exit(1);
+}