@pellux/goodvibes-agent 1.0.31 → 1.0.34

package/docs/release-and-publishing.md

@@ -1,17 +1,17 @@
 # Release And Publishing
 
-GoodVibes Agent's current installable `1.0.x` version is recorded in `package.json` and `CHANGELOG.md`.
+GoodVibes Agent's current installable version is recorded in `package.json` and `CHANGELOG.md`.
 
 ## Package Identity
 
 - registry package: `@pellux/goodvibes-agent`
 - executable: `goodvibes-agent`
-- SDK dependency: exact pin to `@pellux/goodvibes-sdk@0.33.35`
+- SDK dependency: exact pin to `@pellux/goodvibes-sdk@0.33.36`
 - runtime: Bun `1.3.10` or newer
 - source language: TypeScript
 - package docs: every Markdown file under `docs/*.md`
 - connected host ownership: outside Agent
-- current release line: `1.0.x`
+- current release line: stable patch releases
 
 End users install and run GoodVibes Agent with Bun:
 
@@ -24,7 +24,11 @@ Do not add non-Bun install instructions for this product. The package is hosted
 
 ## Required Gates
 
-Before any release candidate or patch release:
+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.
+
+Before any stable release or patch release:
 
 ```sh
 bun install
@@ -46,13 +50,13 @@ 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 current `1.0.x` patch releases, use product-facing notes that summarize the complete patch contents, not only the first fix in the batch. The original 1.0 release candidate used `--notes-file release/1.0-release-notes.md`, and release metadata verification keeps that artifact with the release readiness and live-verification evidence. 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 `release/1.0-*` evidence files 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.
+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.
 
 `--skip-validation` is only allowed with `--dry-run`. Real releases must run the validation gates above.
 
-`--dry-run` is non-mutating and may be used from a dirty or non-main worktree to preview the next version and generated changelog section. For current `1.0.x` patch previews, use `bun run scripts/release.ts --dry-run --patch --notes-file ./release-notes.md`. The historical 1.0 major cut used `bun run scripts/release.ts --dry-run --major --notes-file release/1.0-release-notes.md`. Real releases still require a clean worktree on `main`.
+`--dry-run` is non-mutating and may be used from a dirty or non-main worktree to preview the next version and generated changelog section. For patch previews, use `bun run scripts/release.ts --dry-run --patch --notes-file ./release-notes.md`. Real releases still require a clean worktree on `main`.
 
 The GitHub release workflow publishes to npm only when the repository variable `PUBLISH_NPM` is `true` and the repository secret `NPM_TOKEN` is configured. Without those repository settings, the workflow still validates and creates the GitHub release, but npm publish must be run from a local environment with an exported token. After optional npm publish, the workflow installs the exact registry version into an isolated Bun home, seeds a connected-host token sentinel, captures stdout and stderr for `--version`, `--help`, and `status --json`, and fails without printing that sentinel. Shared release metadata verification requires those publish, exact-version registry lookup, install smoke, and token-sentinel markers to remain in the release workflow.
 
@@ -64,11 +68,11 @@ Shared release metadata verification requires branch CI to run the compiled bina
 
 Shared release metadata verification requires `architecture:check` to keep the Agent/TUI product-boundary rules: no runtime imports from `goodvibes-tui/src`, no coding-TUI git/worktree header posture in the Agent shell, isolated Agent Knowledge client/routes, typed operator contracts, explicit dependency ownership, source-size limits, and no explicit `any` or process-global test mocks.
 
-Shared release metadata verification requires `perf:check` to load `release/1.0-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 1.0 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 `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, and onboarding capability bundles, including local-signal, local-behavior, and external-outcome accounting.
+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 release candidates and real releases: compiled CLI checks, connected-host token/URL discovery, connected-host status/health/model routes, isolated Agent Knowledge status/ask/search routes, SDK-version mismatch skip policy, JSON/Markdown report artifacts, strict mode, and Agent Knowledge contamination guards.
+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.
 
 Do not add targeted `bun test` passes or separate release-only test gates to CI, release, or aggregate scripts. Tests that matter for release must be included in the single full branch-CI suite.
 
@@ -103,4 +107,4 @@ Do not ship connected-host binaries from this package. If Agent later gets compi
 
 ## Product Rule
 
-The `1.0.x` line can include mature terminal foundation code, but package-facing behavior must follow Agent product policy. Follow-up patch releases should continue pruning or reshaping coding-first surfaces while preserving the renderer, input, fullscreen workspace, command registry, and release foundation.
+Stable patch releases can include mature terminal foundation code, but package-facing behavior must follow Agent product policy. Follow-up patch releases should continue pruning or reshaping coding-first surfaces while preserving the renderer, input, fullscreen workspace, command registry, and release foundation.

package/docs/tools-and-commands.md

@@ -1,83 +1,174 @@
 # Tools and Commands
 
-GoodVibes Agent is an operator assistant TUI. Its command set is centered on main-conversation assistant work, isolated Agent Knowledge, local memory/notes/routines/skills/personas, approvals, automation visibility, and explicit delegation to GoodVibes TUI for build work.
+GoodVibes Agent is a TUI-first operator assistant. The workspace is the primary user surface; slash commands are power-user routes inside the TUI; CLI subcommands are scriptable mirrors.
 
-## Product Boundaries
+## Boundaries
 
 - Normal chat stays in the main Agent conversation.
 - Agent Knowledge uses only `/api/goodvibes-agent/knowledge/*`.
-- Agent never falls back to default knowledge or arbitrary non-Agent knowledge spaces.
-- Local memory, notes, routines, skills, and personas remain Agent-local unless an explicit Agent workflow promotes reviewed material into another Agent-owned surface.
-- Runtime hosting is external. Agent connects to it and reports health; it does not start, stop, restart, or install it.
-- Delegated review is not a default reasoning path. It is requested only when the user explicitly asks for build, implementation, fix, or review work.
-- Code-building work is delegated to GoodVibes TUI through public shared-session/task contracts.
+- Agent does not query default knowledge or other product knowledge spaces.
+- Connected-host lifecycle is external. Agent reports and uses public routes, but does not start, stop, restart, install, expose, or mutate the host listener.
+- Code-building work is explicit delegation to GoodVibes TUI. Delegated review is never the default reasoning path.
+- External delivery, notifications, reminders, media generation, setting writes, keybinding writes, UI routing, slash-command execution, workspace-action execution, local destructive changes, and connected-host operator actions require explicit user request and confirmation.
 
-## TUI-First Operator Surface
+## User-Facing Surfaces
 
-The Agent workspace is the product surface. Slash commands are power-user routes inside the TUI, and package CLI subcommands are scriptable mirrors. New user-facing features should appear in the workspace first.
+High-signal TUI routes:
 
-High-signal Agent TUI paths:
+| Surface | Purpose |
+| --- | --- |
+| `/agent` | Open the fullscreen operator workspace. |
+| `/help` and `/commands` | Discover registered slash commands. |
+| `/health`, `/compat`, `/auth` | Inspect runtime, SDK, host, and auth posture. |
+| `/model`, `/provider`, `/effort` | Inspect or change provider/model/reasoning routes. |
+| `/knowledge` | Use isolated Agent Knowledge. |
+| `/memory`, `/notes`, `/personas`, `/skills`, `/routines` | Manage Agent-local behavior libraries. |
+| `/plan`, `/workplan` | Planning and durable visible work tracking. |
+| `/approval`, `/automation`, `/schedule` | Read posture and run exact confirmed operator actions. |
+| `/channels`, `/notify`, `/qrcode` | Pair companions, inspect channel readiness, and send confirmed messages. |
+| `/media`, `/voice`, `/tts` | Inspect media/voice readiness, generate media, and run spoken turns. |
+| `/mcp`, `/secrets`, `/settings`, `/config` | Inspect or update Agent-local configuration. |
+| `/delegate` | Hand explicit build/fix/review work to GoodVibes TUI. |
+
+## Model Tools
+
+| Tool | Use |
+| --- | --- |
+| `agent_harness` | Discover and operate user-facing harness surfaces. |
+| `agent_knowledge` | Read isolated Agent Knowledge: status, ask/search, lists, item, map, connectors. |
+| `agent_knowledge_ingest` | Confirmed ingest into isolated Agent Knowledge. |
+| `agent_local_registry` | Inspect or update Agent-local memory, notes, personas, skills, bundles, and routines. |
+| `agent_work_plan` | Keep the visible Agent-local work plan current. |
+| `agent_operator_briefing` | Read connected work, approvals, automation, schedules, and capacity posture. |
+| `agent_operator_action` | Run exact confirmed approval/automation/schedule actions. |
+| `agent_channel_send` | Send one confirmed channel message. |
+| `agent_notify` | Send one confirmed notification through configured webhook targets. |
+| `agent_reminder_schedule` | Create one confirmed connected reminder/schedule. |
+| `agent_media_generate` | Generate one confirmed image/video artifact. |
 
-- `/help` for registry-driven command discovery.
-- `/health` and `/auth` for runtime/auth/SDK diagnostics inside the TUI.
-- `/model` and `/provider` for provider/model selection and visibility.
-- `/agent` for the fullscreen operator workspace: setup, provider/model, Agent Knowledge, memory, notes, personas, skills, routines, channels, MCP/tools, secrets, voice/media, work state, automation, and build delegation.
-- Agent Workspace -> Research for read-only web research, URL inspection, source triage, and explicit source-to-Agent-Knowledge handoff.
-- Agent Workspace -> Notes for local source-triage notes, temporary decisions, and operator handoff. Notes do not write memory or Agent Knowledge by themselves; reviewed notes can prefill memory, skills, routines, personas, or an isolated Agent Knowledge URL ingest.
-- `/knowledge` for isolated Agent Knowledge ask, search, status, source/node/issue inspection, connector inspection, and confirmed ingest/reindex actions.
-- `/memory`, `/routines`, `/skills`, and `/personas` for Agent-local context and reusable operator behavior.
-- `/plan` for Agent-owned workspace planning state in the main conversation.
-- `/workplan` for durable task status over public work-plan routes.
-- `/approval` for pending approval visibility and explicit approval actions.
-- `/schedule` for schedule visibility plus narrow explicit-user-action flows.
-- `/channels` for channel readiness and one-message confirmed channel delivery.
-- `/media` for media provider readiness and confirmed image/video artifact generation.
-- `/delegate` for explicit build/fix/review handoff to GoodVibes TUI.
-- `/mcp`, `/config`, `/settings`, and setup workspaces for Agent-local configuration.
+## `agent_harness`
 
-The installed `goodvibes-agent` command launches the TUI by default. Subcommands such as `status`, `compat`, `knowledge ...`, `ask <question>`, and `search <query>` are secondary scriptable equivalents for diagnostics and automation over the same Agent workspace features.
+Use `agent_harness mode:"summary"` first. Summary and plural catalog modes are compact by default. They return counts, ids, labels, state, and short route hints. Use `includeParameters:true` or a singular inspect mode when the model needs full schemas, policy detail, editor fields, redacted log tail, release artifact data, route hints, or tool parameters.
 
-Host-management and coding-first commands that would imply connected-host lifecycle ownership, separate Agent job creation, execution-isolation ownership, worktree control, or implicit delegated review must remain blocked, read-only, or delegation-only unless they are intentionally adapted to Agent policy.
+Discovery modes:
 
-## Model-Visible Harness Surface
+| Mode | What It Lists |
+| --- | --- |
+| `workspace`, `workspace_categories`, `workspace_actions` | Workspace categories and actions. |
+| `commands`, `cli_commands` | Slash commands and top-level package CLI mirrors. |
+| `panels`, `ui_surfaces` | Built-in panels and visible modal/overlay/picker/workspace surfaces. |
+| `shortcuts`, `keybindings` | Fixed shortcuts and configurable keybindings. |
+| `settings` | Compact Agent setting rows with category, prefix, query, hidden, and limit filters. |
+| `tools` | First-class model tool definitions; schema details require `includeParameters:true` or `tool`. |
+| `channels`, `notifications` | Channel readiness and redacted notification targets. |
+| `provider_accounts`, `model_routing` | Provider auth and provider/model route posture. |
+| `mcp_servers`, `setup_posture`, `pairing_posture`, `delegation_posture` | MCP, setup, pairing, and build-delegation posture. |
+| `security_posture`, `support_bundles`, `media_posture`, `sessions` | Security, bundle route, voice/media, and session/bookmark posture. |
+| `operator_methods` | Public operator and Agent Knowledge method catalog. |
+| `service_posture`, `connected_host`, `daemon` | Endpoint, connected-host, and daemon alias posture. |
+| `release_evidence`, `release_readiness` | Packaged release evidence and release-quality inventory. |
+
+Single-item inspect modes:
+
+| Mode | Lookup Fields |
+| --- | --- |
+| `workspace_action` | `actionId`, `command`, `target`, `query` |
+| `command`, `cli_command` | `command`, `commandName`, `cliCommand`, `target`, `query` |
+| `panel`, `ui_surface`, `keybinding`, `tool` | Exact id/name or `target`/`query` |
+| `channel`, `notification_target`, `provider_account`, `mcp_server` | Exact id or `target`/`query` |
+| `setup_item`, `model_route`, `pairing_route`, `delegation_route` | Exact id/model key or `target`/`query` |
+| `security_finding`, `support_bundle`, `media_provider`, `session` | Exact id/path or `target`/`query` |
+| `get_setting`, `service_endpoint`, `operator_method` | Exact key/id or `target`/`query` |
+| `connected_host_capability` | `capabilityId`, `target`, `query` |
+| `connected_host_status`, `daemon_status` | Live read-only status, no lookup required |
+| `release_evidence_artifact`, `release_readiness_item` | `artifactId`/`itemId`, `target`, `query` |
+
+Effect modes:
+
+| Mode | Effect |
+| --- | --- |
+| `run_workspace_action` | Executes one resolved workspace action through the same editor/command/local bridge as the TUI. |
+| `run_command` | Executes one resolved slash command through the shared command registry. |
+| `open_panel`, `open_ui_surface` | Routes visible shell navigation. |
+| `run_keybinding` | Runs supported shell-safe keybinding actions only. |
+| `set_keybinding`, `reset_keybinding` | Writes the same Agent `keybindings.json` file exposed to the user. |
+| `set_setting`, `reset_setting` | Writes Agent settings through the config/secret managers. |
 
-The main Agent model has an Agent-owned harness bridge rather than generic SDK settings/context control. Use these model tools as the supported parity layer:
+Every effect mode requires `confirm:true` and `explicitUserRequest`. Ambiguous lookups return candidates before any effect runs.
 
-- `agent_harness`: inspect workspace categories/actions and inspect or run one workspace action by action id, command, or lookup text, inspect built-in panels and one panel by id or lookup text, inspect modal/overlay/picker UI surfaces and named operator surfaces by id or lookup text, inspect top-level CLI mirrors and one mirror by command string, command token, or lookup text, inspect fixed shortcuts and configurable keybindings, inspect/change/run one keybinding by action id or lookup text where a shell-safe model route exists, inspect slash commands and one slash command by typed command or lookup text with policy metadata, run concrete slash-command mirrors with confirmation, inspect model tools or one model tool schema, inspect or change Agent settings by exact key or lookup text, inspect connected-host capability boundaries or one connected-host capability, and inspect live connected-host readiness.
-- `agent_local_registry`: inspect and maintain Agent-local memory, notes, personas, skills, skill bundles, and routines. Deleting local records requires `confirm:true` and `explicitUserRequest`.
-- `agent_knowledge` and `agent_knowledge_ingest`: ask/search and ingest into the isolated Agent Knowledge segment.
-- `agent_operator_briefing` and `agent_operator_action`: inspect connected work/approval/automation posture, or run exact confirmed approval/automation actions.
-- `agent_work_plan`: keep the visible Agent-local work plan current from the conversation.
-- `agent_channel_send`, `agent_notify`, `agent_reminder_schedule`, and `agent_media_generate`: perform confirmed external delivery, notification, reminder, or media actions when the user explicitly asks.
+## Workspace Action Execution
 
-`agent_harness` discovery modes are read-only. `summary` reports the model access map; `workspace` and `workspace_categories` list the Agent workspace category catalog with action counts; `panels` lists the built-in panel catalog, and `panel` resolves one panel by `panelId`, `target`, or `query` with current open/focused state plus its matching Agent workspace route; `ui_surfaces` lists modal, overlay, picker, and workspace entrypoints, and `ui_surface` resolves one by `surfaceId`, `target`, or `query` with shell-opener availability and preferred model routes; `cli_commands` lists top-level package CLI mirror metadata, and `cli_command` resolves one mirror by `cliCommand`, `command`, `commandName`, `target`, or `query`, returning parser output for concrete invocations, blocked command tokens, lookup metadata, and preferred in-process model or current-conversation routes; `shortcuts` returns fixed runtime/editor shortcuts plus configurable keybindings; `keybindings` lists the live resolved keybinding table, and `keybinding`, `run_keybinding`, `set_keybinding`, and `reset_keybinding` resolve one action by `actionId`, `target`, `key`, or `query` with default bindings, custom state, config path, lookup metadata, and model-operation route metadata; `commands` lists slash-command descriptions; `command` returns one slash-command detail by `command`, `commandName`, `target`, or `query`, including parsed arguments plus concrete built-in effect/confirmation/preferred-tool/boundary policy metadata for every registered command root, and refuses ambiguous command lookup with candidate commands; `run_command` executes one confirmed slash command using the same `command`, `commandName`, `target`, or `query` resolver and refuses ambiguous command lookup before any handler runs; `workspace_actions` lists Agent workspace actions and can inline editor field schemas with `includeParameters:true`; `workspace_action` and `run_workspace_action` resolve one action by `actionId`, `command`, `target`, or `query`, using the same user-facing action-search fields; inspection returns lookup metadata plus editor schema and `modelExecution` route metadata for every editor action, and execution refuses ambiguous requests with candidate actions before any effect; `tools` lists model tool definitions and can inline JSON schemas with `includeParameters:true`; `tool` returns one model tool schema by `toolName`, `target`, or `query` and refuses ambiguous schema lookup with candidate tools; `settings` returns setting descriptors plus setting policy and accepts `category`, `prefix`, `query`, `includeHidden:true`, and `limit` filters; `get_setting`, `set_setting`, and `reset_setting` resolve one setting by `key`, `target`, or `query`, return lookup metadata on success, and refuse ambiguous matches with candidate settings; `connected_host` returns the connected-host route families, allowed capabilities, blocked capabilities, and first-class tool availability; `connected_host_capability` returns one allowed or blocked connected-host capability by `capabilityId`, `target`, or `query` with related route families and boundary text and refuses ambiguous capability lookup with candidates; and `connected_host_status` performs a live read-only check of the connected-host status and Agent Knowledge status routes and reports endpoint bindings, token posture, SDK compatibility, route readiness, and findings without printing token values.
+`workspace_action` inspection returns editor schemas and `modelExecution` detail. `workspace_actions` can include the same detail with `includeParameters:true`.
 
-`open_ui_surface` is a confirmation-gated visible navigation mode for the same shell surfaces the user can open: Agent workspace, settings, MCP workspace, model/provider/reasoning-effort pickers, TTS provider/voice pickers, session/profile pickers, the panel-picker compatibility route, security/knowledge/subscription operator surfaces, conversation search, prompt-history search, slash-command mode, command browser, file picker, block actions, bookmarks, context inspector, runtime activity monitor, live process output, help, shortcuts, and onboarding. It does not perform hidden operations; use first-class model tools, settings modes, workspace actions, or confirmed slash-command mirrors for actual state changes. Ambiguous UI surface lookup text is refused with candidate surfaces instead of routed.
+Execution routes:
 
-`cli_command` is a read-only inspection mode. Concrete CLI strings are parsed with redacted config overrides; descriptive lookup text searches the same `cli_commands` catalog and returns one match or candidate mirrors when broad. Supported top-level CLI mirrors report `preferredModelTool`, including current-conversation handling for non-interactive run mirrors that must not create hidden nested turns.
+- Local memory, notes, personas, skills, routines, and bundles dispatch through `agent_local_registry`.
+- Confirmed Agent Knowledge URL/file/bookmark/browser-history/connector ingest dispatches through `agent_knowledge_ingest`.
+- Command-backed editors dispatch through `run_command`.
+- Learned-behavior and profile creation use the Agent-local or slash-command bridge.
+- Web research/fetch forms return a main-conversation prompt instead of starting hidden nested work.
+- Selection-based actions accept `recordId` so the model can use the same selected-record flows as the TUI.
 
-`run_keybinding`, `set_keybinding`, and `reset_keybinding` are confirmation-gated control modes. `run_keybinding` executes only keybinding actions with a faithful current-shell route, such as cancel generation, clear screen, open/focus/dismiss visible panel workspace routes, open conversation or prompt-history search, paste through the existing clipboard handler, or open the visible block-action surface. Prompt-editor-only controls, terminal text selection, category cycling, and reserved shortcuts stay visible in descriptors but return unsupported/direct-interaction metadata instead of pretending a hidden model operation exists. `set_keybinding` and `reset_keybinding` write the same Agent `keybindings.json` file exposed by `/keybindings`, reload the runtime keybinding manager, and leave fixed runtime/editor shortcuts read-only. Ambiguous keybinding lookup text is refused with candidate actions instead of guessed.
+## Settings And Keybindings
 
-`open_panel` is a confirmation-gated UI routing mode. It hands a visible panel/workspace route to the current Agent shell bridge and does not mutate connected-host lifecycle, listener posture, or external accounts. Ambiguous panel lookup text is refused with candidate panels instead of routed.
+Settings discovery accepts `category`, `prefix`, `query`, `includeHidden:true`, and `limit`. It is compact by default; use `includeParameters:true` or `get_setting` for full descriptions/defaults. Single setting reads/writes resolve by `key`, `target`, or `query`; ambiguous matches are refused. Secret-backed setting writes store raw values through the secret manager and return redacted output. Connected-host lifecycle/listener settings are read-only in Agent.
 
-CLI mirror modes are catalog and parser inspection only. When the user asks the model to operate from inside the main conversation, use the returned first-class model tool, workspace action, setting mode, or confirmed slash-command mirror instead of launching a hidden nested `goodvibes-agent` process.
+Keybinding discovery returns fixed shortcuts plus the live resolved binding table. `run_keybinding` only executes actions with faithful current-shell routes. Prompt-editor-only shortcuts, terminal text selection, category cycling, and reserved shortcuts stay direct user interaction.
 
-Setting writes, setting resets, supported keybinding actions, keybinding writes/resets, UI surface routing, slash-command invocation, workspace-action invocation, local record deletion, channel sends, notifications, reminders, media generation, and connected-host operator mutations require explicit user request and confirmation. Secret-backed settings are stored through the secret manager, and connected-host lifecycle/listener settings remain read-only in Agent.
+## Connected Host And Daemon
 
-Selection-based local workspace actions use the same bridge. `agent_harness` reports the required model tool for each local action; for actions that depend on the TUI selection, call `run_workspace_action` with the selected local `recordId` plus an `actionId`, `command`, `target`, or `query` that resolves to one action. Direct local create editors for memory, notes, personas, skills, and routines can execute from submitted `fields` through `run_workspace_action`; the harness validates required fields, requires `confirm:true` and `explicitUserRequest`, and dispatches through `agent_local_registry`. Command-backed editor forms report their shared slash-command dispatch route, direct learned-behavior/profile forms report their local or command bridge, and web research/fetch forms report that execution returns a main-conversation prompt instead of starting hidden nested work. Note promotion actions can prefill and create memory, personas, skills, routines, or isolated Agent Knowledge URL ingests through the matching first-class model tool. Profile creation schemas include the current runtime starter-template inventory, and routine schedule schemas prefill the selected routine when `recordId` or a `routineId` field matches a local routine.
+The connected host is external. Agent can inspect it through:
 
-Use first-class Agent tools before falling back to slash-command mirrors. Slash-command execution is for harness parity and scriptable mirrors, not for bypassing Agent product boundaries.
+- `service_posture` and `service_endpoint` for endpoint binding, network-facing posture, issues, optional probes, and redacted log tail.
+- `connected_host` and `daemon` for compact connected-host posture; use `includeParameters:true` for route families, allowed capabilities, blocked lifecycle/non-Agent surfaces, and first-class tool availability.
+- `connected_host_capability` for one allowed or blocked capability.
+- `connected_host_status` and `daemon_status` for live read-only readiness checks.
+- `operator_methods` and `operator_method` for the public method catalog.
 
-The main composer supports inline context references. Type `@path/to/file`, `@path/to/folder`, or `@https://example.test/page` in a normal prompt to add bounded context for that turn. `!@path/to/file` remains the raw file-injection form. These references do not ingest anything into Agent Knowledge unless the user explicitly runs a Knowledge ingest action.
+None of those modes expose host start, stop, restart, install, expose-listener, account creation, arbitrary route mutation, default knowledge access, hidden background Agent jobs, or implicit delegated review.
 
-The Research workspace submits web research and URL inspection forms to the normal main conversation. These requests are read-only by default, may use connected web tools when the user asks, and do not ingest sources. Use confirmed Agent Knowledge ingest actions only after a source should become durable Agent-owned knowledge.
+## Agent Knowledge
 
-Local memory capture/add commands are explicit Agent-local actions. Deletes, imports/exports, record linking, review-state changes, and promotion across memory scopes require `--yes`.
+Use the Knowledge workspace first. Scriptable mirrors:
+
+```sh
+goodvibes-agent ask "<query>"
+goodvibes-agent search "<query>"
+goodvibes-agent knowledge list --kind sources
+goodvibes-agent knowledge get <id>
+goodvibes-agent knowledge map
+goodvibes-agent knowledge connectors
+goodvibes-agent knowledge connector <connector-id>
+goodvibes-agent knowledge connector-doctor <connector-id>
+goodvibes-agent knowledge ingest-url <url> --yes
+goodvibes-agent knowledge import-urls <path> --yes
+goodvibes-agent knowledge import-bookmarks <path> --yes
+goodvibes-agent knowledge reindex --yes
+```
+
+Agent rejects route-selection flags that would target another knowledge space, including `--space`, `--knowledge-space`, `--knowledge-space-id`, and `--include-all-spaces`. Contaminated connected-host responses return `scope_contamination`.
+
+## Approvals, Automation, And Schedules
+
+Read views are safe by default. Mutations require exact target ids and confirmation:
+
+```text
+/approval approve <approval-id> [--note <text>] [--remember|--no-remember] --yes
+/approval deny <approval-id> [--note <text>] [--remember|--no-remember] --yes
+/approval cancel <approval-id> [--note <text>] [--remember|--no-remember] --yes
+/automation job run <job-id> --yes
+/automation job pause <job-id> --yes
+/automation job resume <job-id> --yes
+/automation run cancel <run-id> --yes
+/automation run retry <run-id> --yes
+/automation schedule run <schedule-id> --yes
+/schedule run <schedule-id> --yes
+```
+
+Routine promotion is an explicit scheduling bridge. Local routines stay local until a user confirms promotion. Delivery targets are opt-in with explicit channel/route/webhook/link flags.
 
 ## Slash Command Catalog
 
-Every registered slash-command root in the Agent TUI is listed here. Aliases resolve through the same command registry but are intentionally secondary to the canonical roots.
-
 | Command | Purpose |
 | --- | --- |
 | `/accounts` | Review provider auth routes, subscription windows, and billing-path safety. |
@@ -106,7 +197,7 @@ Every registered slash-command root in the Agent TUI is listed here. Aliases res
 | `/help` | Show available commands and keyboard shortcuts. |
 | `/image` | Attach an image file to the next message. |
 | `/keybindings` | List keyboard bindings and the config file path. |
-| `/knowledge` | Use isolated Agent Knowledge sources, graph, review queue, ask/search, ingest, and compact prompt packets. |
+| `/knowledge` | Use isolated Agent Knowledge. |
 | `/load` | Load a saved Agent session. |
 | `/mcp` | Manage MCP servers, trust posture, and tool inventory. |
 | `/media` | Inspect media providers or generate media through configured providers. |
@@ -125,13 +216,13 @@ Every registered slash-command root in the Agent TUI is listed here. Aliases res
 | `/qrcode` | Print companion pairing details and a QR code. |
 | `/quit` | Exit the application. |
 | `/redo` | Redo the last undone conversation turn. |
-| `/refresh-models` | Refresh model catalog, benchmarks, and token limits. |
+| `/refresh-models` | Refresh model catalog, metadata, and token limits. |
 | `/reset` | Clear display and conversation context. |
 | `/retry` | Re-send the last user message, optionally with modified text. |
 | `/routines` | Manage Agent-local routines and explicit routine schedule promotion. |
 | `/save` | Save the current session. |
 | `/schedule` | Inspect schedules, create confirmed reminders, and promote routines to connected schedules. |
-| `/secrets` | Manage hierarchy-aware secrets, external secret refs, and secure/plaintext storage policy. |
+| `/secrets` | Manage secrets, external secret refs, and storage policy. |
 | `/security` | Inspect security posture, attack paths, and review state. |
 | `/session` | Inspect session continuity and cross-session graph state. |
 | `/sessions` | List saved sessions. |
@@ -146,83 +237,14 @@ Every registered slash-command root in the Agent TUI is listed here. Aliases res
 | `/tts` | Submit a normal prompt and play the assistant response through live TTS. |
 | `/undo` | Undo the last conversation turn. |
 | `/unpin` | Unpin a model from the favorites list. |
-| `/voice` | Review voice posture and package portable voice interaction metadata. |
+| `/voice` | Review voice posture and portable voice metadata. |
 | `/welcome` | Open or print the Agent setup guide. |
 | `/workplan` | Track a persistent workspace-scoped work plan. |
 
-## Agent Knowledge
-
-`/knowledge ask <query>` asks the isolated Agent Knowledge environment for a source-backed answer through `/api/goodvibes-agent/knowledge/ask`.
-
-`/knowledge search <query>` searches the same isolated Agent environment through `/api/goodvibes-agent/knowledge/search`.
-
-`/knowledge ingest-url <url> --yes` ingests into Agent Knowledge through `/api/goodvibes-agent/knowledge/ingest/url`. Knowledge ingestion, imports, issue review, reindex, and consolidation are Agent-owned mutations and require `--yes`.
-
-The Knowledge workspace exposes status, source library, connector review, ask, search, and confirmed ingest forms. Scriptable equivalents such as `goodvibes-agent knowledge list --kind sources|nodes|issues`, `goodvibes-agent knowledge get <id>`, `goodvibes-agent knowledge connectors`, and `goodvibes-agent knowledge map` are read-only CLI inspection paths over the same isolated Agent route family.
-
-Workspace ingest forms are the primary user workflow. Scriptable equivalents such as `goodvibes-agent knowledge import-urls <path> --yes`, `goodvibes-agent knowledge import-bookmarks <path> --yes`, and `goodvibes-agent knowledge reindex --yes` are confirmed Agent Knowledge maintenance paths. They call only `/api/goodvibes-agent/knowledge/*`.
-
-The Agent command layer rejects flags that would route knowledge work into another space, including `--space`, `--knowledge-space`, `--knowledge-space-id`, and `--include-all-spaces`. If Agent Knowledge is unavailable, the command fails closed instead of querying a default store.
-
-## Media Artifacts
-
-Agent Workspace -> Voice & Media is the primary media path. Use `Generate media` for a confirmed form that calls configured media providers and stores outputs as GoodVibes artifacts.
-
-`/media providers` lists media provider readiness. `/media generate [--provider <id>] [--model <id>] [--mime <mime>] <prompt> --yes` is the power-user mirror for confirmed image/video generation. Media generation output returns artifact ids and metadata; it does not print inline base64 and does not write to default knowledge or non-Agent knowledge segments.
-
-## Planning
-
-`/plan` inspects or seeds Agent workspace planning state. The planning loop belongs to the main Agent conversation: the Agent asks focused questions, records decisions and gaps, and keeps execution separate until the user gives an explicit action.
-
-The SDK planning service may expose a namespace such as `project:<projectId>` because that is the stable contract shape. In Agent UI and docs this is treated as a planning namespace, not as permission to query default knowledge or another product knowledge segment.
-
-Use `/workplan` when the work already has concrete tasks and needs durable status tracking rather than another planning interview.
-
-## Delegation
-
-`/delegate` is for explicit build, fix, review, or implementation work. It sends a single delegated request to GoodVibes TUI/shared-session routes with the original user ask and execution intent. Agent does not create coding-role Agent jobs and does not run delegated review by default.
-
-Use `/delegate --review` only when the user explicitly asks for review or when the delegated build/fix/review request explicitly calls for review.
-
-## Approvals And Automation
-
-Approvals and automation are safe by default:
-
-- list/status views are read-only;
-- mutating routes require exact commands and explicit confirmation such as `--yes`;
-- no chat turn silently runs approval, schedule, or automation mutations;
-- unavailable routes return structured errors rather than fallback behavior.
-
-Workspace forms are the primary path for approval and automation actions:
-
-- Agent Workspace -> Work & Approvals -> Approve request / Deny request / Cancel request
-- Agent Workspace -> Automation -> Run job now / Pause job / Resume job
-- Agent Workspace -> Automation -> Cancel run / Retry run / Run schedule now
-
-Power-user slash mirrors are exact and confirmation-gated:
-
-- `/approval approve <approval-id> [--note <text>] [--remember|--no-remember] --yes`
-- `/approval deny <approval-id> [--note <text>] [--remember|--no-remember] --yes`
-- `/approval cancel <approval-id> [--note <text>] [--remember|--no-remember] --yes`
-- `/automation job run <job-id> --yes`
-- `/automation job pause <job-id> --yes`
-- `/automation job resume <job-id> --yes`
-- `/automation run cancel <run-id> --yes`
-- `/automation run retry <run-id> --yes`
-- `/automation schedule run <schedule-id> --yes`
-- `/schedule run <schedule-id> --yes`
-
-Routine promotion is an explicit scheduling bridge: local routines stay local during normal use, and promotion creates a schedule only after a user runs the exact command with `--yes`. The generated scheduled prompt keeps Agent Knowledge isolated and forbids default knowledge or non-Agent knowledge fallback. Delivery is opt-in with explicit flags such as `--delivery-channel`, `--delivery-route`, `--delivery-webhook`, or `--delivery-link`; no delivery target is inferred from chat.
-
-## Channels
-
-Agent Workspace -> Channels is the primary channel path. It shows readiness, setup, account, policy, and status views without rendering secret values. `Send channel message` opens a confirmed form for one delivery target.
-
-`/channels send --channel <surface[:route[:label]]> --message <text> --yes` sends one explicit message through configured delivery strategies. `--route`, `--webhook`, and `--link` are alternate one-target forms. Channel sends do not create routes, authorize accounts, manage connected-host hosting, use default knowledge, use non-Agent knowledge segments, create separate Agent jobs, or run delegated review.
-
 ## Related Docs
 
-- [Getting started](getting-started.md)
-- [Connected host](connected-host.md)
-- [Knowledge, artifacts, and multimodal](knowledge-artifacts-and-multimodal.md)
-- [Release and publishing](release-and-publishing.md)
+- [Getting Started](getting-started.md)
+- [Connected Host](connected-host.md)
+- [Knowledge, Artifacts, and Multimodal](knowledge-artifacts-and-multimodal.md)
+- [Channels, Remote Access, and API](channels-remote-and-api.md)
+- [Release And Publishing](release-and-publishing.md)

package/docs/voice-and-live-tts.md

@@ -20,7 +20,7 @@ GoodVibes Agent supports spoken turns as an Agent TUI feature. Text output remai
 
 `/config tts` opens the fullscreen configuration workspace for streaming provider, voice, and spoken-turn model routing.
 
-The model can inspect the same settings through `agent_harness` settings modes, open the visible TTS provider or voice picker through `open_ui_surface`, and change Agent-owned TTS settings with explicit confirmation. Connected-host listener or lifecycle settings remain outside Agent ownership.
+The model can inspect the same settings through `agent_harness` settings modes, open the visible TTS provider or voice picker through `open_ui_surface`, and change Agent-owned TTS settings with explicit confirmation. `media_posture` is compact by default; use `includeParameters:true` or `media_provider` for full provider readiness, generation route hints, picker routes, and media policy detail. Connected-host listener or lifecycle settings remain outside Agent ownership.
 
 ## Playback Requirements
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-agent",
-  "version": "1.0.31",
+  "version": "1.0.34",
   "private": false,
   "description": "GoodVibes personal operator assistant TUI with a proactive Agent product brain, isolated Agent Knowledge, local profiles, routines, skills, personas, and explicit build delegation.",
   "type": "module",
@@ -22,7 +22,12 @@
     "tsconfig.json",
     "README.md",
     "CHANGELOG.md",
-    "docs/*.md"
+    "docs/*.md",
+    "release/release-notes.md",
+    "release/performance-snapshot.json",
+    "release/release-readiness.json",
+    "release/live-verification/live-verification.json",
+    "release/live-verification/live-verification.md"
   ],
   "scripts": {
     "dev": "bun run src/main.ts",
@@ -82,7 +87,7 @@
   },
   "dependencies": {},
   "devDependencies": {
-    "@pellux/goodvibes-sdk": "0.33.35",
+    "@pellux/goodvibes-sdk": "0.33.36",
     "sql.js": "^1.14.1",
     "sqlite-vec": "^0.1.9",
     "zustand": "^5.0.12",