@pellux/goodvibes-agent 1.0.33 → 1.0.34

package/docs/README.md

@@ -1,8 +1,8 @@
 # GoodVibes Agent Docs
 
-These are the package-facing docs for the GoodVibes Agent `1.0.x` release line, the personal operator assistant TUI for GoodVibes.
+These are the package-facing docs for the GoodVibes Agent `1.0.x` release line.
 
-Current package docs:
+## Current Docs
 
 - [Getting Started](getting-started.md)
 - [Connected Host](connected-host.md)
@@ -14,22 +14,26 @@ Current package docs:
 - [Project Planning](project-planning.md)
 - [Release And Publishing](release-and-publishing.md)
 
-Important baseline constraints:
-
-- Agent installs one executable: `goodvibes-agent`.
-- Current package version is recorded in `package.json`; the top `CHANGELOG.md` section is the latest completed `1.0.x` release in this tree.
-- Agent uses Bun `1.3.10` or newer and TypeScript-authored source.
-- Agent depends on `@pellux/goodvibes-sdk@0.33.36`.
-- Agent connects to a GoodVibes host owned outside this product.
-- Agent does not start, stop, restart, install, uninstall, or own the connected GoodVibes host.
-- User-facing Agent workspace categories/actions, single workspace-action lookup/execution, built-in panels and single-panel lookup, modal/overlay/picker UI surfaces and single-surface lookup, named operator surfaces, top-level CLI mirrors and single-mirror lookup with preferred model routes, fixed shortcuts, configurable keybindings, single-keybinding lookup, shell-safe keybinding execution, slash commands, single-command lookup with effect, boundary, and preferred-route policy metadata, channel readiness summary/search/single-channel lookup, redacted notification target summary/search/single-target lookup, provider account summary/search/single-provider lookup, MCP server summary/search/single-server lookup with trust, role, quarantine, and tool inventory posture, setup/onboarding posture summary/search/single-item lookup, provider/model routing posture summary/search/single-route-or-model lookup, pairing posture summary/search/single-route lookup, delegation posture summary/search/single-route lookup, security posture summary/search/single-finding lookup, support/auth/trust/subscription/voice bundle route discovery and redacted bundle inspection, voice/media posture summary/search/single-provider lookup, session/bookmark posture summary/search/single-session lookup, compact model tools with optional schema inlining and individual model tool schemas, release evidence bundle summary/search/single-artifact lookup, release-readiness inventory summary/search/single-item lookup, settings catalog filtering and single-setting lookup, local registries, public operator method catalog, single operator method inspection, service endpoint posture, single service endpoint inspection, connected-host capability boundaries, single connected-host capability inspection, and live connected-host readiness are model-visible through Agent-owned tools. Visible UI routing includes the command browser, reasoning-effort picker, live process output, runtime activity, settings, workspaces, and pickers the user can open. Every workspace editor descriptor reports model-execution route metadata, and local memory, note, persona, skill, and routine create editors can also run through confirmed workspace actions. Mutations, visible UI routing, keybinding execution, channel delivery, notification delivery, provider auth changes, setup apply/import/profile changes, provider/model selection/refresh/favorite/custom-provider changes, pairing/manual-token/companion connection changes, delegation submissions, security/trust/bundle export-import changes, voice/media generation and voice toggle changes, session/bookmark save/resume/export/delete changes, and MCP server configuration/trust/role/quarantine changes remain explicit and confirmation-gated; prompt-editor-only shortcuts stay direct user interaction; and ambiguous lookup matches are refused with candidates instead of guessed.
-- Agent Knowledge uses only `/api/goodvibes-agent/knowledge/*`; there is no default knowledge or non-Agent product fallback.
-- Agent supports isolated Agent homes with `GOODVIBES_AGENT_HOME=<path>` and named profile homes with `goodvibes-agent profiles create <name> --template <starter> --yes` plus `--agent-profile <name>`.
-- Agent supports connected-host URL overrides with `--runtime-url http://host:port` or `GOODVIBES_AGENT_RUNTIME_URL=http://host:port`; these only change the Agent connection target.
-- Agent ships starter profile templates for household, research, travel, operations, and personal productivity local state; `profiles templates export/import` and `/agent-profile guide` support local custom starters.
-- First-run setup can seed an initial scratchpad note, local persona, skill, and routine without writing to connected-host knowledge or non-Agent segments.
-- Local memory, notes, personas, routines, and Agent skills are stored under the Agent home. Notes are scratchpad records; reviewed memory, personas, routines, and skills are injected only into the serial Agent conversation.
-- Normal assistant chat is not coding-session delegation.
-- Build/fix/review delegation to GoodVibes TUI must be explicit; delegated review is not the default Agent behavior.
-
-The Agent docs above define supported `1.0.x` behavior.
+## Baseline
+
+- Package executable: `goodvibes-agent`.
+- Install/runtime: Bun `1.3.10` or newer.
+- Current Agent version: `package.json`.
+- SDK pin: exact `@pellux/goodvibes-sdk@0.33.36` version in `package.json`.
+- Connected host: owned outside Agent; Agent reports and uses it but does not manage lifecycle.
+- Agent Knowledge: only `/api/goodvibes-agent/knowledge/*`; no default knowledge fallback.
+- Local state: memory, notes, personas, skills, routines, sessions, setup, and profiles live under the Agent home.
+- Build/fix/review work: explicit delegation to GoodVibes TUI, not normal chat behavior.
+
+## Model Access Baseline
+
+Agent-owned model tools expose the same user-facing harness surfaces:
+
+- `agent_harness` for workspace actions, slash commands, settings, panels, UI surfaces, keybindings, tool schemas, service/daemon posture, connected-host capability/status, release evidence, and posture catalogs.
+- `agent_knowledge` and `agent_knowledge_ingest` for isolated Agent Knowledge.
+- `agent_local_registry` for Agent-local memory, notes, personas, skills, bundles, and routines.
+- `agent_work_plan` for visible local work-plan state.
+- `agent_operator_briefing` and `agent_operator_action` for public connected operator state and exact confirmed actions.
+- `agent_channel_send`, `agent_notify`, `agent_reminder_schedule`, and `agent_media_generate` for explicit confirmed effects.
+
+Catalog modes are compact by default. Detailed schemas, route hints, redacted log tail, release artifact data, and editor fields require `includeParameters:true` or a singular inspect mode. Mutations, external delivery, UI routing, keybinding changes, setting writes, local destructive actions, media generation, reminders, and connected-host operator actions remain confirmation-gated and refuse ambiguous lookup.

package/docs/channels-remote-and-api.md

@@ -19,9 +19,9 @@ Agent-local memory, routines, skills, and personas are not automatically broadca
 
 The model can inspect pairing posture with `agent_harness` mode `pairing_posture`, and inspect one pairing route with mode `pairing_route` using `pairingRouteId`, `target`, or `query`. Those pairing modes return endpoint binding, pairing surface id, route catalog, and token fingerprint only; raw tokens and QR payloads are never returned by the read-only posture modes. QR display, manual token display, companion connection, channel delivery, task, approval, provider/model, and attachment actions stay visible user flows.
 
-The model can inspect channel-facing workspace actions with `agent_harness`, list the structured channel readiness map with `agent_harness` mode `channels`, and inspect one channel with mode `channel` using `channelId`, `target`, or `query`. Those readiness modes are read-only: they return setup state, delivery posture, risk labels, safe config-key names, default-target key names, and preferred model routes without printing secret values or sending messages. The model can send one explicit configured delivery through `agent_channel_send` only when the user asks for that exact effect. It must not create routes, authorize accounts, infer recipients, or expose new public surfaces from chat.
+The model can inspect channel-facing workspace actions with `agent_harness`, list the structured channel readiness map with `agent_harness` mode `channels`, and inspect one channel with mode `channel` using `channelId`, `target`, or `query`. Channel discovery is compact by default. Use `includeParameters:true` or single-channel inspection when the model needs delivery target shape, read-only connected-route hints, or full route metadata. These modes are read-only: they return setup state, delivery posture, risk labels, safe config-key names, and default-target key names without printing secret values or sending messages. The model can send one explicit configured delivery through `agent_channel_send` only when the user asks for that exact effect. It must not create routes, authorize accounts, infer recipients, or expose new public surfaces from chat.
 
-The model can inspect configured notification target posture with `agent_harness` mode `notifications`, and inspect one redacted target with mode `notification_target` using `notificationTargetId`, `target`, or `query`. Those notification modes return target count, validity, protocol/host posture, fingerprints, and management route hints, but not full webhook URLs. Use `agent_notify` for one explicit confirmed notification. Use confirmed `/notify` mirrors for target management only when the user supplies the exact add/remove/clear/test intent.
+The model can inspect configured notification target posture with `agent_harness` mode `notifications`, and inspect one redacted target with mode `notification_target` using `notificationTargetId`, `target`, or `query`. Notification discovery is compact by default. Use `includeParameters:true` or single-target inspection when management route hints are needed. These modes return target count, validity, protocol/host posture, and fingerprints, but not full webhook URLs. Use `agent_notify` for one explicit confirmed notification. Use confirmed `/notify` mirrors for target management only when the user supplies the exact add/remove/clear/test intent.
 
 ## Companion And Session Routes
 

package/docs/connected-host.md

@@ -69,13 +69,13 @@ Agent owns the operator assistant TUI, local profiles, local memory/notes/routin
 
 Agent does not own connected-host lifecycle. It does not provide commands to install, expose, start, stop, restart, or mutate the connected GoodVibes host.
 
-The model can inspect this boundary with `agent_harness` mode `connected_host`. That report includes the configured base URL, token presence, token path, allowed route families, first-class Agent tool capabilities, tool availability, and blocked capabilities. Allowed capabilities include read-only operator briefing, explicit allowlisted approval/automation/schedule actions, isolated Agent Knowledge status/ask/search/source/node/issue/item/map/connector reads, isolated Agent Knowledge ingest, confirmed channel or notification delivery, confirmed reminder schedules, and configured media generation. Blocked capabilities include connected-host lifecycle, listener mutation, default or non-Agent knowledge fallback, hidden background Agent jobs, implicit delegated review, route/account creation, and arbitrary connected-host mutations. To inspect one surface without parsing the full report, use `connected_host_capability` with `capabilityId`, `target`, or `query`; it returns either the allowed capability with related route families or the blocked capability with the boundary reason.
+The model can inspect this boundary with `agent_harness` mode `connected_host`. `daemon` is an alias for the same posture report. By default the report is compact: configured base URL, token posture, ownership, mode hints, and capability counts. Use `includeParameters:true` for full route families, allowed capabilities, blocked capabilities, and first-class Agent tool availability. Allowed capabilities include read-only operator briefing, explicit allowlisted approval/automation/schedule actions, isolated Agent Knowledge read/ingest, confirmed channel or notification delivery, confirmed reminder schedules, and configured media generation. Blocked capabilities include connected-host lifecycle, listener mutation, default or non-Agent knowledge fallback, hidden background Agent jobs, implicit delegated review, route/account creation, and arbitrary connected-host mutations. To inspect one surface without parsing the full report, use `connected_host_capability` with `capabilityId`, `target`, or `query`.
 
 The model can inspect the public operator method catalog with `agent_harness` mode `operator_methods`. That report lists the allowlisted read and mutation methods, their public routes, owning first-class model tools, confirmation policy, and boundary. To inspect one method without parsing the full report, use `operator_method` with `methodId`, `target`, or `query`. This is a read-only catalog and does not expose arbitrary route invocation.
 
-The model can inspect service posture with `agent_harness` mode `service_posture`. That report exposes the same read-only endpoint binding, network-facing posture, issue, and redacted-log diagnostics used by status, doctor, and support bundles. To inspect one endpoint without parsing the full report, use `service_endpoint` with `endpointId`, `target`, or `query`; valid endpoint ids are `controlPlane`, `httpListener`, and `web`. These modes are diagnostic only and do not expose host start, stop, restart, install, listener, or account-management operations.
+The model can inspect service posture with `agent_harness` mode `service_posture`. That report exposes the same read-only endpoint binding, network-facing posture, issue, and redacted-log diagnostics used by status, doctor, and support bundles. Use `includeParameters:true` when reachability probes and redacted log tail are needed. To inspect one endpoint, use `service_endpoint` with `endpointId`, `target`, or `query`; valid endpoint ids are `controlPlane`, `httpListener`, and `web`. These modes are diagnostic only and do not expose host start, stop, restart, install, listener, or account-management operations.
 
-The model can inspect live connected-host readiness with `agent_harness` mode `connected_host_status`. That report uses the same read-only status probe as the CLI: it checks the connected-host status route, verifies the SDK version pin, checks the isolated Agent Knowledge status route when token and version posture allow it, reports endpoint bindings and token posture without printing token values, and returns actionable findings. It is diagnostic only and does not expose host start, stop, restart, install, listener, or account-management operations.
+The model can inspect live connected-host readiness with `agent_harness` mode `connected_host_status`. `daemon_status` is an alias. That report uses the same read-only status probe as the CLI: it checks the connected-host status route, verifies the SDK version pin, checks the isolated Agent Knowledge status route when token and version posture allow it, reports endpoint bindings and token posture without printing token values, and returns actionable findings. `includeParameters:true` adds route family and capability detail. It is diagnostic only and does not expose host start, stop, restart, install, listener, or account-management operations.
 
 The model can inspect companion pairing posture with `agent_harness` mode `pairing_posture`, and inspect one pairing/mobile route with `pairing_route`. Those modes report the control-plane endpoint binding, pairing surface id, token presence/fingerprint, and route catalog without returning raw tokens or QR payloads. Pairing display, manual token display, companion connection, channel delivery, task, approval, provider/model, and attachment actions remain visible user flows.
 

package/docs/getting-started.md

@@ -1,16 +1,14 @@
 # Getting Started
 
-GoodVibes Agent is the installable `1.0.x` personal operator assistant built on the GoodVibes TUI foundation.
+GoodVibes Agent is the installable `1.0.x` personal operator assistant TUI for GoodVibes.
 
 ## Requirements
 
-- Bun `1.3.10` or newer
-- A connected GoodVibes host compatible with `@pellux/goodvibes-sdk@0.33.36`
-- A token/config path accepted by the connected host
+- Bun `1.3.10` or newer.
+- A connected GoodVibes host compatible with the exact `@pellux/goodvibes-sdk@0.33.36` pin in `package.json`.
+- Connected-host token/config state accepted by that host.
 
-Agent does not launch the connected host for you.
-
-Use the interactive TUI first. CLI subcommands are secondary support paths for install checks, setup inspection, and scriptable mirrors of workflows that are already reachable from the workspace.
+Agent does not launch or manage the connected host.
 
 ## Install From Package
 
@@ -20,13 +18,15 @@ goodvibes-agent --help
 goodvibes-agent
 ```
 
-If the installed command is not found, add Bun's global bin directory to `PATH`:
+If `goodvibes-agent` is not on `PATH`:
 
 ```sh
 export PATH="$(bun pm bin -g):$PATH"
 goodvibes-agent --help
 ```
 
+`goodvibes-agent` starts the interactive TUI. On a fresh Agent home, setup opens first. After setup is applied, the TUI opens directly into the Agent workspace.
+
 ## Run From Source
 
 ```sh
@@ -36,130 +36,131 @@ bun install
 bun run dev
 ```
 
-`bun run dev` starts the Agent TUI. The same entrypoint backs the installed `goodvibes-agent` command.
-
-`goodvibes-agent` starts the interactive Agent TUI. On a fresh Agent home, the TUI opens Agent setup first.
-
-After setup has been applied once, the TUI opens directly into the Agent operator workspace. You can also reopen it with `/agent`, `/home`, or `/operator`. That fullscreen workspace is the current front door for setup/config, conversation/session controls, provider/model selection, read-only web research, Agent Knowledge, local memory/notes/skills/routines/personas, channel readiness, voice/media setup, read-only work/approval/automation views, and explicit GoodVibes TUI build delegation.
-
-Press `/` inside the Agent workspace to search every workspace action by name, category, command, or detail. Use that finder before reaching for shell commands; CLI subcommands are scriptable mirrors of these TUI workflows.
-
-The model can inspect and use the same harness surface through Agent-owned tools. `agent_harness` exposes workspace category discovery, workspace action discovery, single workspace-action inspection and execution by action id, command, or lookup text, built-in panel discovery/routing by panel id or lookup text, modal/overlay/picker UI surface discovery/routing by surface id or lookup text, top-level CLI mirror discovery and single-mirror lookup by command string, command token, or lookup text, fixed shortcut and configurable keybinding discovery, keybinding inspection/mutation by action id or lookup text, confirmation-gated shell-safe keybinding execution, slash-command discovery, single slash-command inspection by typed command or lookup text, concrete built-in command effect, boundary, and preferred-route policy metadata, single slash-command execution by typed command or lookup text with confirmation, channel readiness discovery and single-channel inspection by id or lookup text, redacted notification target discovery and single-target inspection by id or lookup text, provider account discovery and single-account inspection by provider id or lookup text, MCP server discovery and single-server inspection by id or lookup text, setup/onboarding posture discovery and single setup-item inspection by id or lookup text, provider/model routing discovery and single route-or-model inspection by id or lookup text, companion pairing posture discovery and single pairing-route inspection by id or lookup text, explicit build-delegation posture discovery and single delegation-route inspection by id or lookup text, redacted security posture discovery and single-finding inspection by id or lookup text, support/auth/trust/subscription/voice bundle route discovery and redacted existing-bundle inspection by path, voice/media readiness discovery and single-provider inspection by id or lookup text, session/bookmark posture discovery and single saved-session inspection by id or lookup text, compact model tool discovery with optional schema inlining and single-tool schema inspection, release evidence bundle discovery with summary, search, and single-artifact lookup, release-readiness inventory discovery with summary, search, and single-item lookup, settings catalog filtering plus inspection/mutation by key or lookup text, public operator method catalog and single-method inspection, service posture and single-endpoint inspection, connected-host capability inventory, single connected-host capability inspection, and live connected-host readiness posture.
+## First Run
 
-CLI mirror modes are read-only catalog/parser inspection and point the model to the matching in-process tool, workspace action, setting mode, slash-command mirror, or current-conversation response route. Panel modes expose catalog/open state and route visible panel/workspace changes through the current Agent shell bridge with confirmation. UI surface modes expose help, shortcuts, command browser, conversation search, prompt-history search, slash-command mode, file picker, block actions, context, runtime activity, live process output, bookmarks, model/provider/reasoning-effort pickers, TTS provider/voice pickers, session/profile pickers, the panel-picker compatibility route, security/knowledge/subscription operator surfaces, settings, MCP workspace, onboarding, and Agent workspace entrypoints; `open_ui_surface` is confirmation-gated and only performs visible shell navigation. Shortcut modes expose the fixed runtime/editor shortcuts and the live keybindings table; keybinding descriptors include a model operation route, `run_keybinding` executes supported shell-safe equivalents only with confirmation, prompt-editor-only or terminal-selection shortcuts remain direct user interaction, and confirmed keybinding edits write the same `keybindings.json` file the user edits and reload the runtime manager.
+Use the interactive workspace first. CLI subcommands are secondary support paths for install checks, setup inspection, and scriptable mirrors.
 
-Workspace action discovery can include editor field schemas with `includeParameters:true`, including starter-template defaults for profile creation and selected-routine defaults for routine schedule promotion when `recordId` is supplied; model tool discovery can include JSON schemas with `includeParameters:true`; channel readiness discovery can include target-shape hints with `includeParameters:true`; notification target discovery can include management-route hints with `includeParameters:true`; provider account discovery can include login/logout route hints with `includeParameters:true`; MCP server discovery can include per-server tool inventory with `includeParameters:true`; setup posture discovery can include model route hints with `includeParameters:true`; model routing discovery can include mutation-route hints with `includeParameters:true`; pairing posture discovery can include connected-host/channel route hints with `includeParameters:true`; delegation posture discovery can include delegation route hints with `includeParameters:true`; security posture discovery can include finding detail with `includeParameters:true`; support bundle route discovery can include route parameter hints with `includeParameters:true`; voice/media posture discovery can include model route hints with `includeParameters:true`; session discovery can include saved-session file paths and search snippets with `includeParameters:true`; release evidence discovery can include artifact source/data with `includeParameters:true`; release-readiness discovery can include source and quality detail with `includeParameters:true`; operator method discovery can include parameter hints with `includeParameters:true`; service posture discovery can include reachability probes and redacted log tail with `includeParameters:true`; every editor descriptor reports `modelExecution` route metadata, and single-action lookup and execution use the same user-facing search fields, return lookup metadata where the action result carries descriptors, and refuse ambiguous run requests with candidates.
+Primary first-run areas:
 
-Single-CLI-mirror, single-panel, single-surface, single-keybinding, single-slash-command, single-channel, single-notification-target, single-provider-account, single-MCP-server, single-setup-item, single-model-route-or-model, single-pairing-route, single-delegation-route, single-security-finding, single-support-bundle, single-voice-media-provider, single-saved-session, single-tool, single-release-evidence-artifact, single-release-readiness-item, single-operator-method, single-service-endpoint, single-setting, and single-connected-host-capability lookup use their catalog search fields, return lookup metadata where the result carries it, and refuse ambiguous route, schema, capability, or mutation requests with candidates; confirmed slash-command execution uses the same slash-command lookup and refuses ambiguous requests before any handler runs. Selection-based local workspace actions accept a local `recordId`, so the model can use the same note promotion and local registry flows as the TUI. Direct local create editors for memory, notes, personas, skills, and routines can execute from submitted fields through `run_workspace_action` and `agent_local_registry` with confirmation. Command-backed editor forms execute through the shared slash-command registry with confirmation, and web research/fetch forms return the main-conversation prompt for the model to use directly. First-class model tools cover the main product workflows directly: Agent Knowledge status/ask/search, source/node/issue lists, item lookup, map summary, connector list/detail/doctor, Agent Knowledge ingest, Agent-local memory/notes/personas/skills/routines, operator actions, notifications, channel sends, reminders, generated media, and work plans.
+- Setup: provider/model, connected-host compatibility, Agent Knowledge readiness, profiles, support bundles, subscriptions, and auth review.
+- Home: normal chat, operator briefing, model selection, and health.
+- Knowledge: isolated Agent Knowledge status, ask/search, inspection, and confirmed ingest.
+- Memory & Skills: local memory, notes, personas, skills, routines, and learned behavior capture.
+- Channels: companion pairing, channel readiness, notification targets, and confirmed sends.
+- Voice & Media: TTS setup, image input, and confirmed generated media.
+- Work & Automation: work-plan tracking, approvals, schedules, reminders, and explicit operator actions.
 
-Use the Artifacts area for concrete files and generated output: attach images to prompts, export conversations or saved sessions, ingest local source files and URL lists into Agent Knowledge, import bookmarks or browser history, inspect source records, and generate media artifacts from confirmed prompts.
+Press `/` inside the Agent workspace to search actions by name, category, command, or detail.
 
-The setup workspace scans Agent-local behavior folders and shows importable persona, skill, and routine files before asking you to create blank records. It can also create one initial scratchpad note, local persona, skill, and routine from the setup form. Use the workspace action finder to search for local behavior discovery/import actions, preview files, then import reviewed records from the matching workspace.
+## Model Access
 
-Use the Profiles workspace Starter authoring guide to walk through starter-profile authoring. It lists built-in and local starters, exports a JSON starter for editing, imports the edited starter back into this Agent home, and creates isolated profiles from the result.
+The main Agent model can use the same user-facing harness through Agent-owned tools. Use `agent_harness mode:"summary"` for a compact map, then drill into plural catalogs or single-item inspect modes.
 
-Use the Profiles workspace form to assemble a local starter template and isolated Agent profile from reviewed discovered persona, skill, and routine files. Scriptable profile commands mirror the same flow for automation; use them only when you intentionally want a shell-driven setup path.
+Default discovery is intentionally compact:
 
-Use the Knowledge area in that workspace to ingest source URLs, local files, URL-list files, bookmarks, browser history, and connector input without leaving the TUI. Every ingest path requires typed confirmation and writes only to the isolated Agent Knowledge segment.
+- plural modes return ids, labels, counts, safe state, and route hints;
+- singular modes return detailed policy and lookup metadata;
+- `includeParameters:true` adds schemas, editor fields, model routes, parameter hints, release artifact data, redacted log tail, and detail that would be too large for normal discovery.
 
-Use the Voice & Media area to review media provider readiness, attach images to conversation prompts, and generate image/video artifacts from a confirmed form. Generated media stays in GoodVibes artifact storage and returns artifact ids for follow-up conversation or delegation; it is not written into default knowledge or non-Agent knowledge segments.
+Common model routes:
 
-Use the Routines workspace receipt actions to review redacted local routine promotion history and reconcile those receipts with live connected schedules through public `schedules.list`. The `/schedule receipts` and `/schedule reconcile` commands are the power-user equivalents inside the TUI.
+| Need | Tool Or Mode |
+| --- | --- |
+| Workspace actions | `agent_harness workspace_actions`, `workspace_action`, `run_workspace_action` |
+| Slash commands | `agent_harness commands`, `command`, `run_command` |
+| Settings | `agent_harness settings`, `get_setting`, `set_setting`, `reset_setting` |
+| Visible UI | `agent_harness panels`, `ui_surfaces`, `open_panel`, `open_ui_surface` |
+| Keybindings | `agent_harness shortcuts`, `keybindings`, `keybinding`, `run_keybinding`, `set_keybinding` |
+| Agent Knowledge | `agent_knowledge`, `agent_knowledge_ingest` |
+| Local memory/notes/personas/skills/routines | `agent_local_registry` or confirmed workspace actions |
+| Work plan | `agent_work_plan` |
+| Channels, notifications, reminders, media | `agent_channel_send`, `agent_notify`, `agent_reminder_schedule`, `agent_media_generate` |
+| Operator state/actions | `agent_operator_briefing`, `agent_operator_action`, `operator_methods` |
+| Connected host/daemon posture | `service_posture`, `connected_host`, `connected_host_status`, `daemon`, `daemon_status` |
 
-The local behavior libraries are configured in the TUI first:
-
-- Memory & Skills -> Create memory, Create note, or Capture learned behavior.
-- Notes -> Create note for source triage, temporary decisions, or operator handoff without writing memory or Agent Knowledge.
-- Personas -> Create persona, Use selected, Review selected, or Delete selected.
-- Skills -> Create skill, Create bundle, Enable selected, Review selected, or Delete selected.
-- Routines -> Create routine, Start selected, Enable selected, Promote to schedule, review receipts, or run a confirmed connected schedule.
-- Work -> Add work item, Review work plan, or Update work item status.
-
-The installed CLI mirrors these libraries for scripts, but it is not the primary user workflow.
+All effects require explicit user request and confirmation. Ambiguous lookup is refused with candidates.
 
 ## Isolated Agent Profiles
 
-Use a separate Agent home when you want isolated local state. The normal launch still opens the TUI:
+Use a separate Agent home for isolated local state:
 
 ```sh
 GOODVIBES_AGENT_HOME=/path/to/agent-home goodvibes-agent
 ```
 
-Use named Agent profiles for repeatable local identities from Agent Workspace -> Profiles. The workspace can browse starter templates, create isolated Agent profiles, set or clear the default profile for the next launch, and export/import starter JSON.
-
-Scriptable equivalents for automation and setup scripts:
+Use named Agent profiles from Agent Workspace -> Profiles. Scriptable equivalents:
 
 ```sh
 goodvibes-agent profiles templates
 goodvibes-agent profiles create household --template household --yes
 goodvibes-agent profiles use household --yes
-goodvibes-agent
+goodvibes-agent --agent-profile household
 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 --agent-profile household
 ```
 
-Named profiles isolate Agent-local config, sessions, memory, notes, personas, skills, routines, and setup state under a profile-specific home. `profiles use <name> --yes` makes one profile the default for the next plain `goodvibes-agent` launch; `--agent-profile <name>` still overrides it for one launch, and `profiles default clear --yes` returns plain launches to the base Agent home. 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. They do not start or isolate the connected host by themselves.
+Named profiles isolate Agent-local config, sessions, memory, notes, personas, skills, routines, and setup state. They do not start or isolate the connected host.
+
+## Local Behavior
 
-## Local Memory, Personas, Routines, And Skills
+Memory, notes, personas, routines, and Agent skills are local to GoodVibes Agent. They do not write into default knowledge or other product segments.
 
-Memory, notes, personas, routines, and reusable Agent skills are local to GoodVibes Agent. First-run setup, TUI workspace forms, and CLI commands all write them to Agent-local registries. They do not write into default knowledge or non-Agent knowledge segments.
+Use the workspace first:
 
-Use `Capture learned behavior` in the Agent workspace after reviewing a repeated workflow, lesson, or operating style. It saves one local skill, routine, or persona from the TUI and does not call connected-host mutation routes.
+- Memory & Skills -> Create memory, Create note, or Capture learned behavior.
+- Notes -> Create notes for source triage, temporary decisions, and operator handoff.
+- Personas -> Create, inspect, activate, review, stale, or delete.
+- Skills -> Create, enable/disable, review, bundle, or delete.
+- Routines -> Create, start in chat, review receipts, or explicitly promote to a connected schedule.
+- Work -> Add work item, review work plan, and update status.
 
-Use Agent Workspace -> Research for web research and URL inspection. Research requests run in the normal main conversation, can use connected read-only web tools when you ask, and do not ingest sources. Use confirmed Agent Knowledge ingest actions only when a reviewed source should become durable Agent-owned knowledge.
+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, explicit, confirmation-gated, and keeps Agent Knowledge isolated.
 
-Use Agent Workspace -> Notes for source triage and temporary context. Notes are a scratchpad: they are reviewable local records, but they do not become durable memory or Agent Knowledge unless you explicitly promote them into memory/skills/routines/personas or run a confirmed Agent Knowledge ingest action. A reviewed note with a source URL can prefill the Agent Knowledge URL ingest form so you do not have to copy the URL by hand.
+## Knowledge And Artifacts
 
-Day-one local behavior setup should stay in the fullscreen workspace:
+Use Agent Workspace -> Knowledge for source-backed Agent Knowledge. The valid route family is:
 
-- Personas -> Create persona, then Use selected.
-- Routines -> Create routine, Start selected, or Promote to schedule after entering real timing and confirmation.
-- Skills -> Create skill, Enable selected, and review setup requirements.
-- Memory & Skills -> Create memory, Create note, or Search memory.
-- Channels -> inspect readiness, send one explicit channel delivery message, add notification targets, and send notification messages only through confirmed actions.
+```text
+/api/goodvibes-agent/knowledge/*
+```
 
-Typed slash commands are available for repeat users, but they are not required for the first-run workflow.
+Agent commands fail closed if the route is unavailable or a successful-looking response exposes default-scope metadata.
 
-The active persona plus enabled Agent routines, reviewed memory, and skills are injected into the main serial assistant conversation. Starting a routine records local usage and prints its steps in the main conversation; it does not start background automation. Promoting a routine to a schedule is an explicit `schedules.create` call, requires `--yes`, writes a local redacted promotion receipt, and preserves the rule that Agent Knowledge never falls back to default knowledge or non-Agent knowledge segments.
+Use Agent Workspace -> Research for read-only web research and URL inspection. Research requests do not ingest sources. Use confirmed Agent Knowledge ingest actions when a reviewed source should become durable.
 
-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. The model can inspect the same readiness map through `agent_harness` modes `channels` and `channel`; delivery still goes through `agent_channel_send` only after an explicit user request. Notification target posture is similarly available through `agent_harness` modes `notifications` and `notification_target`, with webhook values redacted; delivery still goes through `agent_notify` only after an explicit user request. 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.
+Use the Artifacts area and Voice & Media workspace for images, source files, generated media, and exported sessions. Generated media returns artifact ids and metadata, not inline base64.
 
-The main assistant conversation can perform narrow confirmed operator actions when the user explicitly asks for a specific target: approve/deny/cancel one approval, run/pause/resume one automation job, cancel/retry one automation run, or run one schedule. Those calls use only public connected-host routes, require confirmation, and do not create, edit, or delete automation definitions.
+## Connected Host
 
-When the main assistant conversation needs to change Agent settings, inspect/change/run supported Agent keybindings, open a visible UI surface, or run a user-facing harness action, it should use `agent_harness` rather than generic SDK context/settings tools. Panel, UI surface, keybinding, and setting descriptors report lookup metadata when resolved from `target` or `query`; ambiguous route or mutation requests return candidates instead of guessing. Settings catalog discovery accepts `category`, `prefix`, `query`, `includeHidden:true`, and `limit`, and setting descriptors also report writability, workspace visibility, and lock reasons. Keybinding descriptors report fixed shortcuts, resolved bindings, defaults, custom state, config path, and model-operation route; unsupported prompt-editor-only shortcuts stay direct user interaction instead of hidden model operations. UI surface descriptors report the visible shell opener, preferred model route, and confirmation policy; secret-backed settings store raw values through the secret manager; connected-host lifecycle settings stay read-only in Agent; and destructive local record deletion requires explicit confirmation.
+Start the owning GoodVibes host before using connected features. Agent expects:
 
-## Connected GoodVibes Host
+```text
+http://127.0.0.1:3421
+```
 
-Start the owning GoodVibes host before using connected Agent features. Agent expects that host to expose the public operator/Agent routes, including:
+Override for one launch:
 
-- `GET /status`
-- `GET /api/goodvibes-agent/knowledge/status`
-- `POST /api/goodvibes-agent/knowledge/ask`
-- `POST /api/goodvibes-agent/knowledge/search`
-- `GET /api/goodvibes-agent/knowledge/sources`
-- `GET /api/goodvibes-agent/knowledge/nodes`
-- `GET /api/goodvibes-agent/knowledge/issues`
-- `GET /api/goodvibes-agent/knowledge/items/{id}`
-- `GET /api/goodvibes-agent/knowledge/map`
-- `GET /api/goodvibes-agent/knowledge/connectors`
-- `GET /api/goodvibes-agent/knowledge/connectors/{id}`
-- `GET /api/goodvibes-agent/knowledge/connectors/{id}/doctor`
-- `POST /api/goodvibes-agent/knowledge/ingest/url`
-- `POST /api/goodvibes-agent/knowledge/ingest/artifact`
-- `POST /api/goodvibes-agent/knowledge/ingest/urls`
-- `POST /api/goodvibes-agent/knowledge/ingest/bookmarks`
-- `POST /api/goodvibes-agent/knowledge/ingest/browser-history`
-- `POST /api/goodvibes-agent/knowledge/ingest/connector`
-- `POST /api/goodvibes-agent/knowledge/reindex`
+```sh
+goodvibes-agent --runtime-url http://host:port
+```
+
+Persistent shell/session override:
+
+```sh
+export GOODVIBES_AGENT_RUNTIME_URL=http://host:port
+```
 
-If the GoodVibes API is not on `http://127.0.0.1:3421`, pass `--runtime-url http://host:port` for a one-off TUI launch or set `GOODVIBES_AGENT_RUNTIME_URL=http://host:port` before launching the TUI.
+Host diagnostics:
 
-Agent Knowledge is an Agent-owned product segment. Agent commands must not fall back to default knowledge or other product-specific knowledge spaces. Successful responses that expose default-scope metadata are treated as scope contamination and fail closed.
+- Agent Workspace -> Home -> Host compatibility
+- Agent Workspace -> Home -> Doctor diagnostics
+- Agent Workspace -> Home -> Review health
+- `goodvibes-agent status --json`
+- `goodvibes-agent doctor`
+- `goodvibes-agent compat`
 
-Host lifecycle commands are not part of GoodVibes Agent. Use Agent Workspace -> Home -> Host compatibility, Doctor diagnostics, and Review health for diagnostics. CLI status/doctor/compat commands are scriptable mirrors for install checks. The model-visible `service_posture` harness report exposes the same read-only endpoint binding, network-facing posture, issue, and redacted-log diagnostics used by status, doctor, and support bundles; `service_endpoint` inspects one endpoint by `endpointId`, `target`, or `query`. The model-visible `connected_host` harness report lists usable Agent route families, first-class tool capabilities, and blocked lifecycle/non-Agent surfaces. `connected_host_capability` inspects one allowed or blocked connected-host capability and returns the matching route families, first-class tools, and boundary reason. The model-visible `connected_host_status` report performs the live read-only connected-host status and isolated Agent Knowledge readiness checks, reports SDK compatibility, token posture, endpoint bindings, route readiness, and actionable findings, and still does not expose host start/stop/restart/install operations.
+Model-visible diagnostics are `service_posture`, `service_endpoint`, `connected_host`, `connected_host_status`, `connected_host_capability`, `daemon`, and `daemon_status`. These are read-only and do not expose host lifecycle control.
 
 ## Current Product Notes
 
-Agent uses the mature GoodVibes terminal shell, renderer, input, fullscreen workspace, command registry, and release foundation. The active Agent policy is serial/proactive by default, blocks Agent-owned review/job fanout, and delegates explicit build/fix/review work to GoodVibes TUI instead of turning the Agent into a coding TUI.
+Agent uses the GoodVibes terminal shell, renderer, input, fullscreen workspace, command registry, and release foundation. The active policy is serial/proactive by default, blocks hidden Agent-owned job fanout, and delegates explicit build/fix/review work to GoodVibes TUI instead of turning Agent into a coding TUI.

package/docs/providers-and-routing.md

@@ -11,8 +11,8 @@ Provider and model state should be visible in:
 - `/model` and `/provider`;
 - the Agent operator workspace setup checklist;
 - the TTS configuration workspace when spoken turns are used.
-- `agent_harness` modes `model_routing` and `model_route` when the model needs read-only provider/model route posture, selectable model metadata, pinned model status, reasoning support, context-window posture, and safe setting keys.
-- `agent_harness` modes `provider_accounts` and `provider_account` when the model needs read-only provider auth route posture, subscription freshness, usage windows, route issues, and repair guidance without tokens or authorization codes.
+- `agent_harness` modes `model_routing` and `model_route` when the model needs read-only provider/model route posture, selectable model metadata, pinned model status, reasoning support, context-window posture, and safe setting keys. `model_routing` is compact by default; use `includeParameters:true` or `model_route` for full capabilities and route-change hints.
+- `agent_harness` modes `provider_accounts` and `provider_account` when the model needs read-only provider auth route posture, subscription freshness, usage windows, route issues, and repair guidance without tokens or authorization codes. `provider_accounts` is compact by default; use `includeParameters:true` or `provider_account` for route records, usage windows, issues, notes, and auth-flow hints.
 
 When a selected model is provider-qualified, Agent keeps the runtime provider row and raw model id separate. For example, `openai-subscriber` plus `openai:gpt-5.5` should route as provider `openai-subscriber` and model `gpt-5.5` where the public route expects provider/model fields.
 
@@ -41,7 +41,7 @@ Search, voice, media, and multimodal providers are valid Agent features when the
 
 Outputs that should become durable knowledge must go through Agent Knowledge routes. No provider output should be inserted into default knowledge or another product segment by Agent.
 
-Setting changes are available to the model through `agent_harness` only when the user explicitly asks. `model_routing` is read-only; model/provider selection, catalog refresh, pin/unpin, custom provider edits, and route setting changes stay visible picker, settings, workspace, or slash-command flows. Secret-backed provider or channel values are stored through the secret manager and displayed as redacted references.
+Setting discovery is compact by default and full with `includeParameters:true` or `get_setting`. Setting changes are available to the model through `agent_harness` only when the user explicitly asks. `model_routing` is read-only; model/provider selection, catalog refresh, pin/unpin, custom provider edits, and route setting changes stay visible picker, settings, workspace, or slash-command flows. Secret-backed provider or channel values are stored through the secret manager and displayed as redacted references.
 
 ## Related Docs
 

package/docs/release-and-publishing.md

@@ -24,7 +24,7 @@ Do not add non-Bun install instructions for this product. The package is hosted
 
 ## Required Gates
 
-The release readiness inventory is the release-quality gate for the current release line. `release/release-readiness.json` must list every release capability that GoodVibes Agent is expected to cover, including capabilities owned by Agent, the connected host, the companion app, and release operations. A bare `covered` status is not enough: every inventory item must also carry `quality` evidence for capability coverage, direct user access, model access through Agent tools or harness routes, safety/product boundary, and release evidence. Package verification rejects any release readiness item that is missing those dimensions or marks them as unknown, todo, gap, unverified, or unproven. The packaged Agent exposes the release evidence bundle through `agent_harness` modes `release_evidence` and `release_evidence_artifact`, and exposes the readiness inventory through `release_readiness` and `release_readiness_item`, so the model can inspect what the user can inspect without relying on hidden project context.
+The release-quality inventory, `release/release-readiness.json`, is the capability gate for the current release line. It must list every release capability that GoodVibes Agent is expected to cover, including capabilities owned by Agent, the connected host, the companion app, and release operations. A bare `covered` status is not enough: every inventory item must also carry `quality` evidence for capability coverage, direct user access, model access through Agent tools or harness routes, safety/product boundary, and release evidence. Package verification rejects any inventory item that is missing those dimensions or marks them as unknown, todo, gap, unverified, or unproven. The packaged Agent exposes the release evidence bundle through `agent_harness` modes `release_evidence` and `release_evidence_artifact`, and exposes the inventory through `release_readiness` and `release_readiness_item`, so the model can inspect what the user can inspect without relying on hidden project context.
 
 Use neutral evidence aliases in release evidence.
 
@@ -50,7 +50,7 @@ Shared release metadata verification requires the `prebuild` and `version` packa
 
 `bun run publish:package` publishes from a staged package directory to the package registry. It re-runs the shared package policy checks against the source tree, filters forbidden package paths during staging, and verifies the staged package docs, required package paths, and metadata before invoking npm. If `NPM_CONFIG_USERCONFIG` is already set, the registry publish command uses it. Otherwise the script creates a temporary 0600 registry userconfig from `NODE_AUTH_TOKEN` or `NPM_TOKEN`, uses it for that publish command, and removes it with the staging directory. The publish script is idempotent for reruns: if the exact package version is already present on the registry, it reports that state and exits successfully instead of failing the release retry. Shared release metadata verification requires those staged source/staged policy checks, forbidden-path filtering, docs checks, auth handoff, idempotent lookup, dry-run pack, public publish, and cleanup markers to remain in the publish script.
 
-`bun run release` requires product release notes instead of raw git-log output. Pass `--notes-file ./release-notes.md` or set `GOODVIBES_AGENT_RELEASE_NOTES` before a real release. For patch releases, use product-facing notes that summarize the complete patch contents, not only the first fix in the batch. Release metadata verification keeps `release/release-notes.md` with the release readiness and live-verification evidence, and package verification requires the installed package to ship the same current release evidence bundle: release notes, performance snapshot, readiness inventory, and live-verification JSON/Markdown. Release notes should describe what changed for Agent users: TUI behavior, setup, Agent Knowledge, local behavior libraries, connected-host compatibility, package/install behavior, model-visible harness behavior, and safety policy. Do not use commit hashes as the shipped changelog content.
+`bun run release` requires product release notes instead of raw git-log output. Pass `--notes-file ./release-notes.md` or set `GOODVIBES_AGENT_RELEASE_NOTES` before a real release. For patch releases, use product-facing notes that summarize the complete patch contents, not only the first fix in the batch. Release metadata verification keeps `release/release-notes.md` with the release-quality inventory and live-verification evidence, and package verification requires the installed package to ship the same current release evidence bundle: release notes, performance snapshot, release-quality inventory, and live-verification JSON/Markdown. Release notes should describe what changed for Agent users: TUI behavior, setup, Agent Knowledge, local behavior libraries, connected-host compatibility, package/install behavior, model-visible harness behavior, and safety policy. Do not use commit hashes as the shipped changelog content.
 
 Before it mutates version metadata or creates a tag, `bun run release` checks the declared files under `release/` for existence, non-empty content, final newlines, trailing whitespace, and space-before-tab indentation, then enforces the non-test release gates: typecheck, architecture check, performance check, build, publish check, packed install smoke, verification ledger, pack dry-run, and `git diff --check`. Dry-run previews run the same evidence text hygiene check without writing files, commits, or tags. After it writes the release version, `src/version.ts` fallback, and changelog section, it verifies release metadata and package-facing text policy again, then reruns evidence hygiene and diff hygiene before creating the commit and tag. That package policy check proves `package.json`, `CHANGELOG.md`, and the `src/version.ts` fallback literals agree on the Agent and SDK versions, that the package manifest keeps the required Agent runtime/docs files, exclusions, release/publish script entrypoints, and local CI gate entrypoints without explicitly including forbidden Agent/TUI boundary paths or leaving existing forbidden paths reachable through broad includes, that the local release script still requires product notes, real-release validation, post-mutation package policy, docs staging, and annotated tags, that the GitHub setup action uses the same Bun version as `packageManager`, and that package-facing text is present and still follows Agent docs, rendered CLI help, parser-backed CLI command snippets, parser/type/alias/help/handler/top-level help command coverage, exported package-text source coverage, autocomplete overlay text, context inspector text, in-app help overlays, file/bookmark picker text, live process output text, MCP workspace text, model picker/workspace text, profile/session picker text, process/runtime activity text, search overlays, shared selection/picker chrome, setup/onboarding wizard text, settings workspace text, slash-command registry text, Agent workspace catalog text, route boundaries, install policy, and version pins. The generated changelog heading uses the operator's local release date in `YYYY-MM-DD` form, not UTC rollover time. The prebuild version sync refuses missing, ranged, or otherwise non-exact Agent or SDK versions instead of writing placeholder fallbacks. The release commit stages those metadata files plus every package-facing `docs/*.md` page, so release docs cannot drift outside the tag. The full test suite remains a branch-CI responsibility and must already be green for the release SHA.
 
@@ -70,7 +70,7 @@ Shared release metadata verification requires `architecture:check` to keep the A
 
 Shared release metadata verification requires `perf:check` to load `release/performance-snapshot.json`, validate its render samples and extra SLO/queue/tool/compaction/integration metrics, run the CI performance-budget evaluation, print the formatted report, and exit from the budget result. The release performance snapshot is staged with release metadata so the tag carries the exact non-live fixture used by the branch-CI performance gate.
 
-Shared release metadata verification requires `verification:ledger` to keep JSON and Markdown evidence output plus inventory coverage for settings schema, feature flags, slash commands, built-in panels, top-level CLI commands, external surfaces, onboarding capability bundles, the model-visible release evidence bundle, the model-visible service posture surface, the model-visible channel readiness surface, the model-visible notification target surface, the model-visible provider account surface, the model-visible MCP server surface, the model-visible setup/onboarding surface, the model-visible model routing surface, the model-visible pairing surface, the model-visible delegation surface, the model-visible security/support bundle surface, the model-visible voice/media posture surface, the model-visible sessions/bookmarks surface, the model-visible operator method catalog, and the release quality readiness dimensions from `release/release-readiness.json`, including local-signal, local-behavior, and external-outcome accounting. Package verification also enforces compact model tool registration and schema descriptions so tool metadata stays usable.
+Shared release metadata verification requires `verification:ledger` to keep JSON and Markdown evidence output plus inventory coverage for settings schema, feature flags, slash commands, built-in panels, top-level CLI commands, external surfaces, onboarding capability bundles, the model-visible release evidence bundle, the model-visible service posture surface, the model-visible channel readiness surface, the model-visible notification target surface, the model-visible provider account surface, the model-visible MCP server surface, the model-visible setup/onboarding surface, the model-visible model routing surface, the model-visible pairing surface, the model-visible delegation surface, the model-visible security/support bundle surface, the model-visible voice/media posture surface, the model-visible sessions/bookmarks surface, the model-visible operator method catalog, and the release-quality dimensions from `release/release-readiness.json`, including local-signal, local-behavior, and external-outcome accounting. Package verification also enforces compact model tool registration, wrapped tool definitions, harness catalog defaults, and schema descriptions so tool metadata stays usable.
 
 Shared release metadata verification requires `verification:live` to keep the external-outcome audit for stable releases: compiled CLI checks, connected-host token/URL discovery, connected-host status/health/model routes, isolated Agent Knowledge status/ask/search/source/node/issue/map/connector route checks plus packaged evidence for item inspection, SDK-version mismatch skip policy, JSON/Markdown report artifacts, strict mode, and Agent Knowledge contamination guards.