@pellux/goodvibes-agent 0.1.114 → 0.1.117

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,58 +46,56 @@ 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, 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.
+
+Use the workspace as the primary product surface:
+
+- Home: normal assistant chat, operator briefing, model selection, setup, and health.
+- 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, learned behavior capture, personas, skills, routines, and schedule promotion.
+- Channels: companion pairing, channel readiness, notification routes, and webhook add/remove/test.
+- Automation: reminder creation, schedule status, routine promotion, receipts, and reconciliation.
+- Build Delegation: explicit handoff to GoodVibes TUI for build/fix/review work.
+
+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. It can also create one initial local persona, skill, and routine directly during first-run setup; those records stay in Agent-local registries and never write to default Knowledge/Wiki or non-Agent segments.
 
 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.
 
+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:
+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>`.
 
-```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
-```
+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. The connected GoodVibes host remains shared unless that host is separately configured otherwise.
 
-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
-```
+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.
+
+Local Agent 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 -> Memory & Skills: create memory, search memory, review/stale/delete records, export/import bundles, and rebuild the local vector index.
+- Agent Workspace -> Channels: inspect readiness, pair companion clients, and manage 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; it does not launch local workers 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`.
 
 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.
 
-## 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
 
@@ -113,7 +103,7 @@ GoodVibes Agent owns the operator assistant TUI: serial assistant flow, proactiv
 
 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 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.
 
@@ -122,7 +112,7 @@ GoodVibes TUI owns coding execution: file edits, git/worktree workflows, coding
 Package-facing docs:
 
 - [Getting Started](docs/getting-started.md)
-- [Connected Services](docs/connected-services.md)
+- [Connected Host](docs/connected-host.md)
 - [Release And Publishing](docs/release-and-publishing.md)
 
 The package-facing Agent documentation is limited to the docs listed above.