@pellux/goodvibes-agent 1.0.31 → 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.35`.
-- 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, model tools with optional schema inlining and individual model tool schemas, settings catalog filtering and single-setting lookup, local registries, 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, and keybinding execution 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

@@ -17,7 +17,11 @@ Agent channel UX should show:
 
 Agent-local memory, routines, skills, and personas are not automatically broadcast to channels. External delivery is an effect and requires an exact command, an explicit routine promotion, or a user-approved connected-host request. Companion pairing uses `/pair` without printing the raw token; manual token display requires `/pair --show-token --yes`. One-off delivery uses Agent Workspace -> Channels -> Send channel message or `/channels send ... --yes`.
 
-The model can inspect channel-facing workspace actions with `agent_harness`, and it can send one explicit configured delivery through `agent_channel_send` 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 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`. 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`. 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
 
@@ -43,7 +47,7 @@ Use public SDK/operator routes only. For Agent Knowledge, the only valid family
 /api/goodvibes-agent/knowledge/*
 ```
 
-If an Agent-specific route is missing, fail closed or show guidance. Do not substitute the default knowledge, another product segment, or private connected-host files.
+If an Agent-specific route is missing, fail closed or show guidance. Do not substitute the default knowledge, another product segment, or private connected-host files. If an Agent-specific route returns default scope metadata, treat that as contamination and fail the call.
 
 Harness and settings operations use the Agent-owned `agent_harness` tool. Generic settings/context mutators are not the model-facing Agent contract.
 

package/docs/connected-host.md

@@ -19,9 +19,24 @@ Start the owning GoodVibes host before launching Agent. Agent expects that host
 
 ```text
 http://127.0.0.1:3421
-/api/goodvibes-agent/knowledge/status
-/api/goodvibes-agent/knowledge/ask
-/api/goodvibes-agent/knowledge/search
+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
 ```
 
 If the GoodVibes API is on a different host or port, use a one-off override when launching the TUI:
@@ -54,10 +69,16 @@ 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 are limited to 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`; 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 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 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.
 
-Agent Knowledge is its own product segment. Agent uses `/api/goodvibes-agent/knowledge/*` only and must not fall back to default knowledge or other product-specific knowledge routes.
+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`. `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.
+
+Agent Knowledge is its own product segment. Agent uses `/api/goodvibes-agent/knowledge/*` only and must not fall back to default knowledge or other product-specific knowledge routes. Agent also rejects successful-looking responses that expose default scope metadata or known non-Agent payload markers.
 
 Normal assistant chat uses companion chat. Build/fix/review work is delegated explicitly to GoodVibes TUI through public runtime/session contracts, and delegated review is requested only when explicitly asked for build/fix/review work.

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.35`
-- 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,110 +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.
+## First Run
 
-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, model tool discovery with optional schema inlining and single-tool schema inspection, settings catalog filtering plus inspection/mutation by key or lookup text, connected-host capability inventory, single connected-host capability inspection, and live connected-host readiness posture. 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. 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`; 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. Single-CLI-mirror, single-panel, single-surface, single-keybinding, single-slash-command, single-tool, 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, Agent Knowledge ingest, Agent-local memory/notes/personas/skills/routines, operator actions, notifications, channel sends, reminders, generated media, and work plans.
+Use the interactive workspace first. CLI subcommands are secondary support paths for install checks, setup inspection, and scriptable mirrors.
 
-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.
+Primary first-run areas:
 
-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.
+- 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 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.
+Press `/` inside the Agent workspace to search actions by name, category, command, or detail.
 
-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.
+## Model Access
 
-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.
+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 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.
+Default discovery is intentionally compact:
 
-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.
+- 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.
 
-The local behavior libraries are configured in the TUI first:
+Common model routes:
 
-- 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.
+| 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 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 Memory, Personas, Routines, And Skills
+## Local Behavior
 
-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.
+Memory, notes, personas, routines, and Agent skills are local to GoodVibes Agent. They do not write into default knowledge or other product segments.
 
-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.
+Use the workspace first:
 
-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.
+- 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.
+
+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.
+
+## Knowledge And Artifacts
 
-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.
+Use Agent Workspace -> Knowledge for source-backed Agent Knowledge. The valid route family is:
+
+```text
+/api/goodvibes-agent/knowledge/*
+```
 
-Day-one local behavior setup should stay in the fullscreen workspace:
+Agent commands fail closed if the route is unavailable or a successful-looking response exposes default-scope metadata.
 
-- 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.
+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.
 
-Typed slash commands are available for repeat users, but they are not required for the first-run workflow.
+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 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.
+## Connected Host
 
-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.
+Start the owning GoodVibes host before using connected features. Agent expects:
 
-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.
+```text
+http://127.0.0.1:3421
+```
 
-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.
+Override for one launch:
 
-## Connected GoodVibes Host
+```sh
+goodvibes-agent --runtime-url http://host:port
+```
 
-Start the owning GoodVibes host before using connected Agent features. Agent expects that host to expose the public operator/Agent routes, including:
+Persistent shell/session override:
 
-- `GET /status`
-- `/api/goodvibes-agent/knowledge/status`
-- `/api/goodvibes-agent/knowledge/ask`
-- `/api/goodvibes-agent/knowledge/search`
-- `/api/goodvibes-agent/knowledge/ingest/url`
+```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.
+- 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 `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/knowledge-artifacts-and-multimodal.md

@@ -26,10 +26,16 @@ 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/urls
+POST /api/goodvibes-agent/knowledge/ingest/artifact
 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
 ```
 
@@ -37,7 +43,9 @@ If those routes are unavailable, Agent commands fail closed with a structured er
 
 The CLI and slash-command layers reject route-selection flags such as `--space`, `--knowledge-space`, `--knowledge-space-id`, and `--include-all-spaces` because those would violate the Agent product boundary.
 
-Agent Knowledge writes are explicit-user-action paths. Slash commands that ingest, import, review issues, reindex, or run consolidation require `--yes`; ask/search/status/list paths remain read-only.
+Successful route responses are validated before rendering. If a connected host response exposes default-scope metadata or carries known non-Agent payload markers, Agent returns a `scope_contamination` error instead of treating that payload as isolated Agent Knowledge.
+
+Agent Knowledge writes are explicit-user-action paths. Slash commands that ingest, import, review issues, reindex, or run consolidation require `--yes`; ask/search/status/list/get/map/connector paths remain read-only.
 
 ## Ask And Search
 
@@ -48,9 +56,9 @@ Use Agent Workspace -> Knowledge -> Ask Agent Knowledge for source-backed Agent
 - sources, titles, and URLs when returned;
 - facts, gaps, and refinement task ids only when the Agent Knowledge route returns them.
 
-`--json` preserves the raw structured Agent route response for tooling.
+`--json` preserves the raw structured Agent route response for tooling after the scope-contamination guard accepts the payload.
 
-The command layer does not turn search results into an answer locally and does not apply client-side filters to hide contamination. Isolation must come from the Agent Knowledge route itself.
+The command layer does not turn search results into an answer locally and does not apply client-side filters to hide contamination. It rejects contaminated payloads; the connected host must still return Agent-owned data for the route to succeed.
 
 Use Agent Workspace -> Knowledge -> Search Agent Knowledge for interactive search. `/knowledge search <query>` and `goodvibes-agent search <query>` query the isolated Agent Knowledge search route and render bounded results with title, id, type, score, source, URL, and snippets when available. Empty Agent stores return an explicit empty state.
 
@@ -60,8 +68,12 @@ Read-only inspection is available from the TUI Knowledge workspace first, with C
 - `/knowledge list --kind sources|nodes|issues`
 - `/knowledge get <id>`
 - `/knowledge connectors`
+- `/knowledge connector <connector-id>`
+- `/knowledge connector-doctor <connector-id>`
 - `/knowledge map`
 
+The main assistant conversation can use the read-only `agent_knowledge` tool for the same isolated status, ask, search, source/node/issue list, item lookup, map, connector list, connector detail, and connector doctor workflows.
+
 ## Ingest
 
 Use Agent Workspace -> Knowledge for URL, URL-list, file, bookmark, browser-history, connector ingest, and reindex forms. The main assistant conversation can also call the confirmed `agent_knowledge_ingest` tool for the same isolated source families. `/knowledge ingest-url <url> --yes` and `goodvibes-agent knowledge ingest-url <url> --yes` ingest URL sources into Agent Knowledge only.
@@ -82,7 +94,7 @@ Artifacts are first-class runtime objects for files, images, audio, video, gener
 
 Agent Workspace -> Voice & Media -> Generate media creates image/video artifacts through configured media providers after typed confirmation. The main conversation can perform the same confirmed action with the `agent_media_generate` tool when the user explicitly asks for generated media. Generated media output is summarized as artifact ids, MIME types, filenames, and source URLs when present; inline base64 is not printed into the transcript.
 
-The model can discover the user-facing Knowledge, artifact, research, and media actions with `agent_harness` workspace action modes. When a workspace action maps to a concrete slash command, `agent_harness` can run that command with confirmation. For common product workflows, use the first-class tools first: `agent_knowledge`, `agent_knowledge_ingest`, and `agent_media_generate`.
+The model can use first-class tools for the common Knowledge and media workflows: `agent_knowledge`, `agent_knowledge_ingest`, and `agent_media_generate`. `agent_harness` adds workspace-action lookup/execution, `media_posture`/`media_provider` readiness, `sessions`/`session` bookmark and artifact posture, and confirmed slash-command mirrors when a visible workspace route maps to a concrete command.
 
 Multimodal outputs should stay in the conversation, artifacts, local notes or memory, or explicit delegation results unless the user explicitly ingests a reviewed source through an Agent Knowledge route. They must not be inserted into default knowledge.
 

package/docs/project-planning.md

@@ -19,7 +19,7 @@ The SDK/runtime owns durable storage and route contracts:
 - readiness evaluation and next-question hints;
 - decision records;
 - task, dependency, verification, and assignment metadata;
-- passive operator methods.
+- read-only public operator methods.
 
 Other surfaces can store or inspect planning artifacts, but conversation control stays in Agent. Agent planning state is not default knowledge, another product segment, or arbitrary knowledge data.
 
@@ -70,7 +70,7 @@ The work-plan tracker is for concrete, durable task state after work becomes act
 
 Use `/workplan` when the work already has tasks and needs status tracking. Use `/delegate` when explicit build/fix/review work should go to GoodVibes TUI.
 
-The model can keep the same visible work plan current with `agent_work_plan`. It can also discover `/plan`, `/workplan`, and delegation workspace actions through `agent_harness`; destructive work-plan changes still require explicit user request and confirmation.
+The model can keep the same visible work plan current with `agent_work_plan`. It can also inspect planning/work-plan visibility through `agent_harness` workspace and panel metadata, and inspect explicit build-delegation posture with `delegation_posture`/`delegation_route`; destructive work-plan changes and delegated submissions still require explicit user request and confirmation.
 
 ## Agent Knowledge Boundary
 

package/docs/providers-and-routing.md

@@ -11,7 +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` settings and workspace-action discovery when the model needs to inspect or change Agent-owned routing settings.
+- `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.
 
@@ -40,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. 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