@pellux/goodvibes-agent 1.0.33 → 1.0.35

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 Product-facing release notes for GoodVibes Agent.
 
+## 1.0.35 - 2026-06-04
+
+- Added searchable `agent_harness` mode discovery: `mode:"modes"` searches every harness mode by task, family, effect type, id, alias, and parameter name, while `mode:"mode"` inspects one mode contract.
+- Added full harness mode descriptors for every model-visible harness operation, with compact summaries, families, effect/read-only classification, confirmation flags, aliases, parameter names, and next-step guidance.
+- Compacted registered model tool definitions at runtime: Agent tools now use concise descriptions, generic tool descriptions are capped, and nested JSON-schema descriptions are stripped from the default model-visible catalog while detailed contracts stay inspectable through harness modes.
+- Counted the model-visible harness mode catalog in the verification ledger and package metadata gate so release evidence tracks the new discovery surface.
+- Cleaned the useful test surface for the changed product shape by consolidating repetitive registration tests and adding focused coverage for mode discovery, task-phrase lookup, tool definition compaction, and release ledger accounting.
+- Refreshed package-facing docs, release notes, and readiness evidence for the current model-access contract.
+
+## 1.0.34 - 2026-06-04
+
+- Promoted GoodVibes Agent to the stable 1.0.x operator product surface: the fullscreen Agent workspace is the primary TUI, with setup, provider/model routing, status, compatibility, and doctor flows shaped around personal operator use instead of copied host lifecycle controls.
+- Completed the Agent-local behavior system for day-one operation: local memory and notes, personas, skills, skill bundles, routines, starter profiles, discovery/import flows, review/stale/delete controls, and secret-looking content rejection all stay under Agent ownership.
+- Completed isolated Agent Knowledge coverage across CLI, slash commands, workspace panels, connector/source/node/issue views, URL/file/browser/connector ingest, semantic ask/search, and connected-host `/api/goodvibes-agent/knowledge/*` routes without fallback to default or non-Agent knowledge surfaces.
+- Completed connected-host operator integration without taking host lifecycle ownership: compatibility/status checks, authenticated health and model routes, channel readiness, provider-account posture, approvals, automation snapshots, schedules, work plans, media/voice readiness, pairing, and explicit public-route diagnostics are all visible from Agent.
+- Completed explicit side-effect boundaries for personal operation: channel sends, notifications, routine schedule promotion, reminders, subscription/auth actions, memory bundle imports/exports, support bundles, MCP configuration, profile changes, and build delegation require explicit confirmation where they mutate state or call external routes.
+- Completed package and release hardening for the release gate: Bun-only install/run instructions, package-facing text verification, package runtime bundling, packed global install smoke, blocked lifecycle command smoke, source/package boundary checks, architecture checks, recorded performance snapshot checks, verification ledger, strict live verification artifacts, and release-quality readiness inventory dimensions are now part of the validated release path.
+- Completed the compact model-visible harness pass: `agent_harness` summary and plural catalogs now default to compact rows, with full schemas, policy blocks, route metadata, editor fields, release artifact detail, redacted log tail, and parameter detail behind `includeParameters:true` or singular inspect modes.
+- Completed direct model access to user-facing harness operations: workspace actions, slash commands, settings, panels, UI surfaces, keybindings, tool catalogs, channel/notification posture, provider/account posture, MCP posture, setup, model routing, pairing, delegation, security/support bundles, media, sessions, operator methods, release evidence, and connected-host diagnostics are all exposed through Agent tools or harness modes.
+- Completed connected-host daemon aliases for the model: `daemon` maps to connected-host posture and `daemon_status` maps to live connected-host status while lifecycle control stays outside Agent.
+- Completed settings parity for the model-facing harness: settings discovery is compact by default, `get_setting` and `includeParameters:true` expose full descriptors, and `set_setting`/`reset_setting` use the same config/secret managers with confirmation and external-host setting locks.
+- Completed the tool-description verbosity sweep: first-class Agent tools and wrapped built-in tool definitions now register concise descriptions, while detailed safety rules remain enforced in policy wrappers, confirmation errors, and detailed harness inspection.
+- Completed copyable model route hint cleanup: confirmed harness examples now include the required `confirm:true` and `explicitUserRequest` fields so route hints match the actual execution contract.
+- Completed resilient shortcut/keybinding discovery: `agent_harness` returns fixed shortcuts and default-fallback keybinding descriptors when the live keybinding manager is absent, while keybinding execution and mutation still fail closed until the runtime manager is available.
+- Completed the model-visible operator method catalog: `agent_harness` can now list and inspect allowlisted public operator and Agent Knowledge methods with their owning first-class model tools, confirmation policy, and boundaries, without exposing arbitrary route invocation.
+- Expanded first-class Agent Knowledge reads: `agent_knowledge` now covers status, ask, search, source/node/issue lists, item lookup, map summary, connector list/detail, and connector doctor while staying inside `/api/goodvibes-agent/knowledge/*`.
+- Added fail-closed Agent Knowledge response-scope validation: CLI, model tools, and live verification reject successful-looking payloads that expose default scope metadata or known non-Agent payload markers.
+- Expanded release-route enforcement for Agent Knowledge: architecture/package policy now guards the full route catalog, and live verification definitions include source, node, issue, map, and connector read routes in addition to status, ask, and search.
+- Pinned the release line to `@pellux/goodvibes-sdk@0.33.36` so the packaged connected-host runtime includes Agent Knowledge alias scope normalization and telephony channel surface support.
+- Renamed active release evidence artifacts to current-release paths under `release/`, including release notes, readiness inventory, performance snapshot, and live-verification reports, so current release metadata no longer depends on stale historical filenames.
+
 ## 1.0.33 - 2026-06-04
 
 - Fixed the release lockfile so frozen CI installs resolve @pellux/goodvibes-sdk@0.33.36 and its published peer packages.
@@ -81,7 +112,7 @@ Product-facing release notes for GoodVibes Agent.
 
 ## 1.0.24 - 2026-06-03
 
-- Resolve confirmed agent_harness run_command requests by the same command, commandName, target, or query lookup used for slash-command inspection.
+- Resolve confirmed `agent_harness` `mode:"run_command"` requests by the same command, commandName, target, or query lookup used for slash-command inspection.
 - Refuse ambiguous slash-command run lookups with candidate commands before any handler runs.
 - Refresh package-facing docs, model-facing schema text, and focused harness coverage for slash-command execution parity.
 
@@ -99,13 +130,13 @@ Product-facing release notes for GoodVibes Agent.
 
 ## 1.0.21 - 2026-06-03
 
-- Resolve agent_harness run_workspace_action by actionId, command, target, or query using the same lookup contract as workspace_action inspection.
+- Resolve `agent_harness` `mode:"run_workspace_action"` by actionId, command, target, or query using the same lookup contract as `mode:"workspace_action"` inspection.
 - Refuse ambiguous workspace action run requests with candidate actions instead of requiring exact action ids or guessing.
 - Refresh package-facing docs and focused harness coverage for workspace action run parity.
 
 ## 1.0.20 - 2026-06-03
 
-- Add agent_harness run_keybinding for confirmation-gated shell-safe shortcut equivalents such as search, prompt-history search, paste, clear screen, cancel generation, panel focus/close routes, and visible block-action routing.
+- Add `agent_harness` `mode:"run_keybinding"` for confirmation-gated shell-safe shortcut equivalents such as search, prompt-history search, paste, clear screen, cancel generation, panel focus/close routes, and visible block-action routing.
 - Add modelOperation route metadata to every configurable keybinding so the model can distinguish supported shell routes from prompt-editor-only or direct-interaction shortcuts.
 - Refresh package-facing docs and focused harness coverage for keybinding operation parity.
 
@@ -129,7 +160,7 @@ Product-facing release notes for GoodVibes Agent.
 
 ## 1.0.16 - 2026-06-03
 
-- Add agent_harness workspace_action lookup by actionId, command, target, or query with resolved lookup metadata.
+- Add `agent_harness` `mode:"workspace_action"` lookup by actionId, command, target, or query with resolved lookup metadata.
 - Reuse the user-facing workspace action search fields for single-action inspection while reporting ambiguity with candidate actions instead of guessing.
 - Refresh package-facing docs and focused harness coverage for the updated model-visible workspace action inspection path.
 

package/README.md

@@ -3,30 +3,26 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Status: 1.0.x](https://img.shields.io/badge/status-1.0.x-green.svg)](#install)
 
-GoodVibes Agent is the personal operator assistant TUI for GoodVibes. It is built for day-to-day operator work: chat, setup, local profiles, routines, skills, personas, isolated Agent Knowledge, status review, approvals, automation visibility, and explicit build delegation.
+GoodVibes Agent is the installable personal operator assistant TUI for GoodVibes. It is built for day-to-day operator work: chat, setup, profiles, routines, skills, personas, Agent-local memory and notes, isolated Agent Knowledge, channel readiness, voice/media setup, work-plan tracking, approvals, automation visibility, and explicit build delegation.
 
-The Agent product connects to a GoodVibes host owned outside this package. It does not install, start, stop, restart, or own that host.
-
-Most work happens in the interactive TUI. The installed CLI exists to launch that TUI and provide scriptable mirrors for workflows that are already reachable from the workspace. The main Agent model can inspect the same harness surface through Agent-owned tools: workspace categories/actions and single-action lookup, 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, filtered settings and single-setting lookup, direct channel/notification/provider-account/MCP/setup/model-routing/pairing/delegation/security/support/media/session posture modes, 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, local registries, public operator method catalog, service endpoint posture, connected-host capability boundaries, and live connected-host readiness are all discoverable from the conversation without exposing connected-host lifecycle control.
+Agent connects to a GoodVibes host owned outside this package. It does not install, start, stop, restart, expose, or own that host.
 
 ## Install
 
-Install the current `1.0.x` package with Bun:
-
 ```sh
 bun add -g @pellux/goodvibes-agent
 goodvibes-agent --help
 goodvibes-agent
 ```
 
-If `goodvibes-agent` is not found after installation, add Bun's global bin directory to `PATH`:
+If the command is not on `PATH`, add Bun's global bin directory:
 
 ```sh
 export PATH="$(bun pm bin -g):$PATH"
 goodvibes-agent --help
 ```
 
-`goodvibes-agent` starts the interactive Agent TUI. On a fresh Agent home, the TUI opens Agent setup first.
+On a fresh Agent home, `goodvibes-agent` opens setup first. After setup is applied, it opens directly into the Agent workspace.
 
 ## Source Usage
 
@@ -37,7 +33,7 @@ bun install
 bun run dev
 ```
 
-Useful checks:
+Useful local checks:
 
 ```sh
 bun run typecheck
@@ -46,92 +42,112 @@ bun run package:install-check
 bun run publish:check
 ```
 
-After setup has been applied once, the Agent TUI opens directly into the operator workspace. You can also reopen it with `/agent`, `/home`, or `/operator`. It is the Agent-first fullscreen workspace for setup, conversation/session controls, model/provider selection, isolated Agent Knowledge, local memory/notes/skills/routines/personas, channel readiness, voice/media setup, work-plan/approval review, automation observability, and explicit build delegation to GoodVibes TUI.
+## Operator Workspace
+
+The fullscreen Agent workspace is the primary product surface. Reopen it with `/agent`, `/home`, or `/operator`.
 
-Use the workspace as the primary product surface:
+Workspace areas:
 
 - Home: normal assistant chat, operator briefing, model selection, setup, and health.
-- Conversation: context usage, inline `@file`/`@folder`/`@url` references, compaction, title/session save/load/search/export, transcript search, bookmarks, paste/image/TTS helpers, undo/redo/retry, clear/reset, shortcuts, and keybindings.
-- Research: read-only web research, URL inspection, source triage, and explicit handoff into isolated Agent Knowledge when a source should become durable.
-- Artifacts: image attachment, conversation/session export, source-file ingest, source lookup, bookmark/browser-history import, and generated media artifact handling.
+- Conversation: context usage, inline `@file`/`@folder`/`@url` references, compaction, title/session save/load/search/export, bookmarks, paste/image/TTS helpers, undo/redo/retry, clear/reset, shortcuts, and keybindings.
+- Research: read-only web research, URL inspection, source triage, and explicit handoff into Agent Knowledge.
+- Artifacts: image attachment, conversation/session export, source-file ingest, source lookup, bookmark/browser-history import, and generated media artifacts.
 - Setup: provider/model, compatibility, Agent Knowledge readiness, profiles, support bundles, subscriptions, and auth review.
-- Tools & MCP: MCP server setup, tool inventory, trust review, secret storage/link/test/delete, and settings.
-- Knowledge: isolated Agent Knowledge status, ask/search, source/node/issue libraries, item lookup, map review, connector inspection, URL/URL-list/file/bookmark/browser-history/connector ingest, review queue, and reindex.
+- Tools & MCP: MCP server setup, tool inventory, trust review, secrets, and settings.
+- Knowledge: isolated Agent Knowledge status, ask/search, source/node/issue libraries, item lookup, map review, connectors, ingest, review queue, and reindex.
 - Memory & Skills: local memory, scratchpad notes, learned behavior capture, personas, skills, routines, and schedule promotion.
-- Notes: Agent-local scratchpad for source triage, temporary decisions, and operator handoff. Notes do not become memory or Agent Knowledge unless you explicitly promote or ingest something; reviewed notes can prefill memory, skills, routines, personas, or an isolated Agent Knowledge URL ingest.
-- Channels: companion pairing, channel readiness, confirmed channel delivery, and confirmed webhook add/remove/test/send.
-- Voice & Media: voice review, spoken response setup, image input, confirmed image/video generation, browser-tool posture, MCP inventory, and media provider readiness.
-- Automation: reminder creation, schedule status, routine promotion, receipts, reconciliation, and explicitly confirmed approve/deny/cancel/run/pause/resume/retry actions.
-- Build Delegation: explicit handoff to GoodVibes TUI for build/fix/review work.
+- Channels: companion pairing, channel readiness, confirmed channel delivery, and confirmed webhook notification management.
+- Voice & Media: voice review, spoken response setup, image input, confirmed image/video generation, browser-tool posture, and provider readiness.
+- Automation: reminders, schedule status, routine promotion receipts, reconciliation, and exact confirmed approval/automation/schedule actions.
+- Build Delegation: explicit handoff to GoodVibes TUI for build, fix, implementation, or review work.
 
-Inside the Agent workspace, press `/` to search every workspace action by name, category, command, or detail. This is the primary discovery path for product actions; slash commands and CLI subcommands remain power-user/scriptable mirrors.
+Press `/` inside the workspace to search actions by name, category, command, or detail. Slash commands and CLI subcommands remain power-user/scriptable mirrors; the workspace is the first-class user path.
 
-The model has the same harness map through `agent_harness`: it can list Agent workspace categories, list Agent workspace actions, inspect or run one workspace action by `actionId`, `command`, `target`, or `query`, list built-in panels and inspect one panel by `panelId`, `target`, or `query`, inspect modal/overlay/picker UI surfaces by `surfaceId`, `target`, or `query`, list top-level CLI mirrors and inspect one mirror by `cliCommand`, `command`, `commandName`, `target`, or `query`, inspect fixed shortcuts and configurable keybindings by `actionId`, `target`, `key`, or `query`, run shell-safe keybinding equivalents with confirmation, list slash commands, inspect or run one slash command by `command`, `commandName`, `target`, or `query` with parsed arguments and concrete built-in effect, boundary, and preferred-route policy metadata, inspect model tool definitions with optional schema inlining or one model tool schema, inspect the release evidence bundle by summary, search, or single artifact, inspect the release-readiness inventory by summary, search, or single item, filter/list Agent settings by `category`, `prefix`, `query`, `includeHidden`, and `limit`, inspect or change Agent settings by `key`, `target`, or `query` with confirmation, inspect public operator methods by summary or single method, inspect service posture or one service endpoint, and report connected-host capability and live readiness posture. CLI mirror modes are read-only catalog and parser inspection, and every supported top-level mirror reports the preferred in-process model route or current-conversation route; inside the main conversation, the model uses that returned route instead of launching hidden nested CLI processes. 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 fixed runtime/editor controls plus the live resolved keybinding table; each keybinding descriptor reports its model operation route, `run_keybinding` executes only supported shell-safe equivalents with confirmation, and prompt-editor-only or terminal-selection shortcuts remain explicit direct user interaction. `set_keybinding` and `reset_keybinding` write the same `keybindings.json` file the user edits and require confirmation. Workspace action discovery can inline editor field schemas with `includeParameters:true`; every editor action descriptor reports `modelExecution` route metadata for local-registry, slash-command, direct local-create, prompt-returning, or first-class-tool execution; model tool discovery can inline JSON schemas with `includeParameters:true`; release evidence discovery can inline artifact source/data with `includeParameters:true`; release readiness discovery can inline source and quality detail with `includeParameters:true`; operator method discovery can inline parameter hints with `includeParameters:true`; service posture discovery can include reachability probes and a redacted log tail with `includeParameters:true`; single-action lookup and execution use the same user-facing search fields, return or preserve lookup metadata where the action result carries descriptors, and refuse ambiguous run requests with candidates; CLI mirror, panel, UI surface, keybinding, slash-command, model tool, release-evidence artifact, release-readiness item, operator method, service endpoint, setting, and connected-host capability lookup use their catalog search fields 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; profile editors use the current starter-template inventory, and routine schedule editors can prefill a selected local routine from `recordId`. 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 actions execute through the shared slash-command registry with confirmation, while web research/fetch editor actions return the main-conversation prompt for the model to use directly. The `operator_methods` report exposes the allowlisted public operator and Agent Knowledge method catalog with owning first-class tools; `operator_method` inspects one method by `methodId`, `target`, or `query`, and still does not allow arbitrary route invocation. The `service_posture` report exposes the same 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 `connected_host` report includes route families, allowed capabilities, blocked lifecycle/non-Agent surfaces, and availability for the first-class Agent tools; `connected_host_capability` inspects one allowed or blocked capability by id, target, or query with its route families and boundary. The `connected_host_status` report performs a read-only live check of the connected-host status route and the isolated Agent Knowledge status route, reports SDK compatibility, token posture, endpoint bindings, route readiness, and actionable findings, and still refuses connected-host lifecycle control. The model uses those first-class tools for product workflows where they exist, such as Agent Knowledge status/ask/search, source/node/issue libraries, item lookup, map review, connector inspection, local memory/notes/personas/skills/routines, channel sends, notifications, reminders, media generation, work plans, and connected-host operator actions.
+## Model-Visible Harness
 
-Direct `agent_harness` posture modes cover channel readiness (`channels`/`channel`), notification targets (`notifications`/`notification_target`), provider accounts (`provider_accounts`/`provider_account`), MCP servers (`mcp_servers`/`mcp_server`), setup/onboarding (`setup_posture`/`setup_item`), provider/model routing (`model_routing`/`model_route`), companion pairing (`pairing_posture`/`pairing_route`), explicit build delegation (`delegation_posture`/`delegation_route`), security/support bundles (`security_posture`, `security_finding`, `support_bundles`, `support_bundle`), voice/media (`media_posture`/`media_provider`), and sessions/bookmarks (`sessions`/`session`). These read-only modes return posture, safe ids, counts, route hints, and redacted diagnostics; delivery, setup apply, provider/model changes, pairing/manual-token display, delegation submissions, media generation, auth, trust, bundle, MCP, session, and bookmark mutations stay explicit visible user flows.
+The main Agent model can inspect and operate the same user-facing harness through Agent-owned tools. The important entrypoint is `agent_harness`.
 
-The setup workspace surfaces discovered Agent-local persona, skill, and routine markdown files so day-one setup can import useful behavior instead of starting from blank records. It can also create one initial scratchpad note, local persona, skill, and routine directly during first-run setup; those records stay in Agent-local registries and never write to default knowledge or non-Agent segments.
+`agent_harness mode:"summary"` is compact by default. It returns counts, status, and a short mode guide. `mode:"modes"` searches every harness mode by task, family, effect type, id, alias, or parameter name; `mode:"mode"` inspects one mode contract. Plural catalog modes are also compact by default: they return ids, labels, counts, safe state, and route hints. Use `includeParameters:true` or a singular inspect mode when the model needs schemas, detailed route hints, full policy blocks, redacted log tail, release artifact data, or editor field definitions.
 
-In the Profiles workspace, choose Starter authoring guide to author custom profile starters without leaving the Agent TUI. The guided flow lists starters, exports starter JSON, imports edited local starters, and creates isolated Agent profiles from them.
+High-value `agent_harness` mode groups:
 
-Use the Profiles workspace form to turn reviewed discovered persona, skill, and routine files into a local starter template and isolated Agent profile in one confirmed flow. The scriptable equivalent is `profiles create-from-discovered <name> --yes`; `profiles templates from-discovered <id> --yes` is still available when you only want to save the starter first.
+- Discovery: `modes`, `workspace_categories`, `workspace_actions`, `commands`, `cli_commands`, `panels`, `ui_surfaces`, `shortcuts`, `keybindings`, `tools`, `settings`.
+- Single-item inspection: `mode`, `workspace_action`, `command`, `cli_command`, `panel`, `ui_surface`, `keybinding`, `tool`, `get_setting`.
+- User-visible effects: `run_workspace_action`, `run_command`, `open_panel`, `open_ui_surface`, `run_keybinding`, `set_keybinding`, `reset_keybinding`, `set_setting`, `reset_setting`.
+- Product posture: `channels`, `notifications`, `provider_accounts`, `mcp_servers`, `setup_posture`, `model_routing`, `pairing_posture`, `delegation_posture`, `security_posture`, `support_bundles`, `media_posture`, `sessions`.
+- Connected host: `service_posture`, `service_endpoint`, `connected_host`, `connected_host_status`, `connected_host_capability`; `daemon` and `daemon_status` are aliases for connected-host posture/status.
+- Release evidence: `release_evidence`, `release_evidence_artifact`, `release_readiness`, `release_readiness_item`.
+- Operator methods: `operator_methods`, `operator_method`.
 
-The Knowledge area includes an in-workspace URL ingest form. It writes only to Agent Knowledge, requires typed confirmation, and dispatches the existing isolated `/knowledge ingest-url ... --yes` route. Agent Knowledge calls fail closed if a connected-host response exposes default scope metadata or known non-Agent payload markers.
+Every mutating or externally visible effect requires `confirm:true` plus `explicitUserRequest` unless a narrower first-class tool has its own confirmation contract. Ambiguous lookups return candidates instead of guessing.
 
-The Research workspace submits web research and URL inspection requests back to the normal Agent conversation. These requests can use connected read-only web tools when the user asks, but they do not ingest sources into Agent Knowledge. Use the separate confirmed Agent Knowledge ingest actions when a reviewed source should become durable.
+First-class model tools cover common workflows directly:
 
-The Voice & Media workspace includes `Generate media`, a confirmed form for image/video generation through configured media providers. Generated bytes are stored as GoodVibes artifacts and the transcript shows artifact ids, not inline base64. The power-user mirror is `/media generate [--provider <id>] [--model <id>] [--mime <mime>] <prompt> --yes`; `/media providers` lists readiness.
+- `agent_knowledge` and `agent_knowledge_ingest` for isolated Agent Knowledge reads and confirmed ingest.
+- `agent_local_registry` for Agent-local memory, notes, personas, skills, bundles, and routines.
+- `agent_work_plan` for visible local work-plan tracking.
+- `agent_operator_briefing` and `agent_operator_action` for connected work/approval/automation/schedule posture and exact confirmed actions.
+- `agent_channel_send`, `agent_notify`, `agent_reminder_schedule`, and `agent_media_generate` for confirmed delivery, notification, reminder, and media generation.
 
-Use isolated Agent profiles when one machine needs separate operator identities or local state. In the TUI, open Agent Workspace -> Profiles to browse starters, create a profile, use it as the default for the next launch, clear the default, and export/import starter JSON. The same profile selection is available for one launch with `goodvibes-agent --agent-profile <name>`.
+Registered model tool definitions are compact by default. Top-level descriptions are short, and nested parameter descriptions are omitted from the default model catalog. The model can inspect detailed contracts through `agent_harness mode:"tools"` with `includeParameters:true`, `mode:"tool"`, or the owning harness mode.
 
-Profiles isolate Agent-local config, sessions, local memory, scratchpad notes, personas, skills, routines, and setup state. First-run setup seeds new profiles from a built-in starter by default unless you explicitly choose `No profile`. Starter templates seed local personas, skills, and routines for household, research, travel, operations, and personal productivity profiles; exported starter JSON can be edited and re-imported as a local starter. The connected GoodVibes host remains shared unless that host is separately configured otherwise.
+## Local Behavior
 
-The installed CLI mirrors the same local behavior libraries for scripts and automation, but it is not the primary product path. Personas, skills, memory, and routines are created, reviewed, enabled, exported/imported where relevant, and deleted from the TUI workspace first; destructive actions still require explicit confirmation.
+Agent-local memory, notes, personas, skills, routines, and profiles are stored under the Agent home. They are injected only into the serial Agent conversation unless an explicit Agent workflow promotes or ingests reviewed material elsewhere.
 
-The Agent workspace also has a `Capture learned behavior` form. Use it after reviewing a repeated workflow, lesson, or operating style; it saves one local skill, routine, or persona directly from the TUI and does not write to connected-host routes or non-Agent knowledge.
+Useful workspace paths:
 
-When the user explicitly asks, the main assistant conversation can perform the same narrow operator actions exposed by the TUI: approve/deny/cancel a named approval, run/pause/resume a named automation job, cancel/retry a named automation run, or run a named schedule. These actions require explicit confirmation, use only public connected-host operator routes, and do not create, edit, or delete automation definitions.
+- Memory & Skills -> Create memory, Create note, or Capture learned behavior.
+- Notes -> Create, edit, review, stale, delete, or promote scratchpad notes.
+- Personas -> Create, inspect, activate, review, stale, or delete local personas.
+- Skills -> Create skills, import discovered skills, enable/disable, review, delete, and manage skill bundles.
+- Routines -> Create routines, start a routine in chat, review receipts, and explicitly promote one routine to a connected schedule.
+- Profiles -> Create isolated Agent profiles from built-in or imported starter templates.
 
-When the user explicitly asks the model to operate the harness itself, it should use Agent-owned harness tools rather than generic SDK settings or context mutators. Setting writes, slash-command invocation, workspace action invocation, local record deletion, external delivery, media generation, reminder scheduling, and connected-host operator actions remain confirmation-gated.
+Starting a routine prints its steps in the main conversation. It does not start background automation. Promotion to a connected schedule is separate, explicit, confirmation-gated, and records a redacted local receipt.
 
-Agent-local behavior is editable from the TUI workspace:
+## Knowledge And Artifacts
 
-- Agent Workspace -> Personas: create, inspect, activate, review, stale, and delete local personas.
-- Agent Workspace -> Skills: create skills, import discovered skills, enable or disable them, and manage skill bundles.
-- Agent Workspace -> Routines: create routines, start a routine in the main conversation, review receipts, and explicitly promote one routine to a connected schedule.
-- Agent Workspace -> Work: review the visible local work plan, add work items, and update status from the TUI while the main assistant conversation can keep the same plan current.
-- Agent Workspace -> Memory & Skills: create memory, search memory, review/stale/delete records, export/import bundles, and rebuild the local vector index.
-- Agent Workspace -> Notes: create, edit, review, stale, delete, and promote Agent-local scratchpad notes into memory, skills, routines, or personas.
-- Agent Workspace -> Channels: inspect readiness, pair companion clients, send one confirmed channel delivery message, and manage or send configured notification targets with confirmation.
+Agent Knowledge is its own product segment. Agent uses only:
 
-Slash commands remain available inside the TUI for power users, but the fullscreen Agent workspace is the primary path for these workflows.
+```text
+/api/goodvibes-agent/knowledge/*
+```
+
+Agent does not fall back to default knowledge or other product-specific knowledge routes. Successful connected-host responses are checked for scope contamination before rendering.
 
-Starting a routine records local usage and prints its steps in the main conversation; it does not start background automation. Promotion to a connected schedule is separate and explicit: it calls the public `schedules.create` route only after `--yes`, can include explicit delivery targets such as `--delivery-channel slack`, records a redacted local receipt, and the generated scheduled prompt keeps Agent Knowledge isolated from default knowledge and non-Agent knowledge segments. Use `/schedule reconcile` to compare those local receipts against live connected schedules through public `schedules.list`.
+The Knowledge workspace and model tools support status, ask/search, source/node/issue lists, item lookup, map review, connector inspection, URL/file/URL-list/bookmark/browser-history/connector ingest, review queue, and reindex.
 
-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.
+Artifacts are first-class runtime objects for uploaded files, generated media, and delegated outputs. Generated media is stored as GoodVibes artifacts and reported by artifact id and metadata, not inline base64.
 
 ## Connected Host
 
-Start the owning GoodVibes host before launching Agent. Agent status and companion/knowledge routes normally connect on `http://127.0.0.1:3421`.
+Start the owning GoodVibes host before launching Agent. The default connection is:
+
+```text
+http://127.0.0.1:3421
+```
 
-Use `--runtime-url http://host:port` for a one-off launch, or set `GOODVIBES_AGENT_RUNTIME_URL=http://host:port` when the connected host is not on the default local port. The legacy `GOODVIBES_AGENT_BASE_URL` env var is also accepted as an alias. These only change the connection target; Agent still does not host or start it.
+Use `--runtime-url http://host:port` for one launch or `GOODVIBES_AGENT_RUNTIME_URL=http://host:port` for a shell/session override. `GOODVIBES_AGENT_BASE_URL` is accepted as a legacy alias. These only change the connection target.
 
-Agent reports unavailable, unauthenticated, or incompatible connected-host state from Agent Workspace -> Home through Host compatibility, Doctor diagnostics, and Review health. `goodvibes-agent status`, `goodvibes-agent doctor`, and `goodvibes-agent compat` are scriptable mirrors for install checks. The model-visible `agent_harness` modes `service_posture`, `service_endpoint`, and `connected_host_status` expose service endpoint posture and live readiness from the conversation without printing token values or exposing host lifecycle operations. Host lifecycle stays outside the Agent product.
+Agent reports unavailable, unauthenticated, or incompatible host state from Agent Workspace -> Home through Host compatibility, Doctor diagnostics, and Review health. Scriptable mirrors are `goodvibes-agent status`, `goodvibes-agent doctor`, and `goodvibes-agent compat`.
 
-## Product Boundary
+Model-visible diagnostics are read-only:
+
+- `service_posture` and `service_endpoint` expose endpoint binding, network-facing posture, issues, optional probes, and redacted log tail.
+- `connected_host` and `daemon` are compact posture maps by default; `includeParameters:true` adds route families, allowed capabilities, blocked lifecycle/non-Agent surfaces, and first-class tool availability. `connected_host_capability` inspects one capability.
+- `connected_host_status` and `daemon_status` run live readiness checks for host status, SDK compatibility, token posture, endpoint binding, and isolated Agent Knowledge readiness.
 
-GoodVibes Agent owns the operator assistant TUI: serial assistant flow, proactive safe actions, local memory/notes/routines/skills/personas, Agent Knowledge routes, companion chat, approvals/automation observability, and explicit build delegation.
+Host lifecycle stays outside GoodVibes Agent.
 
-Agent Knowledge is its own product segment. Agent uses `/api/goodvibes-agent/knowledge/*` and must not fall back to default knowledge or other product-specific knowledge routes.
+## Product Boundary
 
-Agent Workspace -> Knowledge can ask/search, inspect sources/nodes/issues, inspect connectors, ingest URL/file/bookmark/browser-history/connector input, and reindex the Agent segment. CLI commands mirror those same isolated Agent Knowledge workflows for scripts. Confirmed mutations require explicit confirmation.
+GoodVibes Agent owns the operator assistant TUI, serial assistant flow, local behavior libraries, Agent Knowledge routes, companion chat, work-plan tracking, approvals/automation observability, channel/media/reminder tools, and explicit build delegation.
 
-GoodVibes TUI owns coding execution: file edits, git/worktree workflows, coding panels, execution isolation UX, and delegated review execution. Agent may delegate explicit build/fix/review work to TUI through public runtime/session contracts; normal assistant chat must not use shared coding sessions.
+GoodVibes TUI owns coding execution: file edits, git/worktree workflows, coding panels, execution isolation UX, and delegated review execution. Agent may delegate explicit build/fix/review work; normal assistant chat does not use shared coding sessions.
 
 ## Package Docs
 
-Package-facing docs:
-
 - [Getting Started](docs/getting-started.md)
 - [Connected Host](docs/connected-host.md)
 - [Knowledge, Artifacts, and Multimodal](docs/knowledge-artifacts-and-multimodal.md)
@@ -141,5 +157,3 @@ Package-facing docs:
 - [Voice and Live TTS](docs/voice-and-live-tts.md)
 - [Project Planning](docs/project-planning.md)
 - [Release And Publishing](docs/release-and-publishing.md)
-
-The package-facing Agent documentation is limited to the docs listed above.