@pellux/goodvibes-agent 0.1.117 → 1.0.0

package/docs/README.md

@@ -6,22 +6,28 @@ Current package docs:
 
 - [Getting Started](getting-started.md)
 - [Connected Host](connected-host.md)
+- [Knowledge, Artifacts, and Multimodal](knowledge-artifacts-and-multimodal.md)
+- [Tools and Commands](tools-and-commands.md)
+- [Channels, Remote Access, and API](channels-remote-and-api.md)
+- [Providers and Routing](providers-and-routing.md)
+- [Voice and Live TTS](voice-and-live-tts.md)
+- [Project Planning](project-planning.md)
 - [Release And Publishing](release-and-publishing.md)
 
 Important baseline constraints:
 
 - Agent installs one executable: `goodvibes-agent`.
-- Agent uses Bun and TypeScript-authored source.
+- Agent uses Bun `1.3.10` or newer and TypeScript-authored source.
 - Agent depends on `@pellux/goodvibes-sdk@0.33.35`.
 - Agent connects to a GoodVibes host owned outside this product.
 - Agent does not start, stop, restart, install, uninstall, or own the connected GoodVibes host.
-- Agent Knowledge/Wiki uses only `/api/goodvibes-agent/knowledge/*`; there is no default Knowledge/Wiki or non-Agent product fallback.
+- Agent Knowledge uses only `/api/goodvibes-agent/knowledge/*`; there is no default knowledge or non-Agent product fallback.
 - Agent supports isolated Agent homes with `GOODVIBES_AGENT_HOME=<path>` and named profile homes with `goodvibes-agent profiles create <name> --template <starter> --yes` plus `--agent-profile <name>`.
 - Agent supports connected-host URL overrides with `--runtime-url http://host:port` or `GOODVIBES_AGENT_RUNTIME_URL=http://host:port`; these only change the Agent connection target.
 - Agent ships starter profile templates for household, research, travel, operations, and personal productivity local state; `profiles templates export/import` and `/agent-profile guide` support local custom starters.
-- First-run setup can seed an initial local persona, skill, and routine without writing to connected-host knowledge or non-Agent segments.
-- Local memory, personas, routines, and Agent skills are stored under the Agent home and are injected only into the serial Agent conversation.
+- First-run setup can seed an initial scratchpad note, local persona, skill, and routine without writing to connected-host knowledge or non-Agent segments.
+- Local memory, notes, personas, routines, and Agent skills are stored under the Agent home. Notes are scratchpad records; reviewed memory, personas, routines, and skills are injected only into the serial Agent conversation.
 - Normal assistant chat is not coding-session delegation.
-- Build/fix/review delegation to GoodVibes TUI must be explicit; WRFC is not the default Agent behavior.
+- Build/fix/review delegation to GoodVibes TUI must be explicit; delegated review is not the default Agent behavior.
 
 The Agent docs above define the supported alpha behavior.

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

@@ -0,0 +1,50 @@
+# Channels, Remote Access, and API
+
+GoodVibes Agent can be reached from terminal-first and companion surfaces, but the Agent product does not own transport hosting. It connects to a GoodVibes host owned outside this package and uses public operator routes for status, sessions, artifacts, approvals, automation, and Agent Knowledge.
+
+## Channel Posture
+
+Channel setup is explicit. Agent can inspect channel readiness, guide pairing, and send one confirmed delivery message through configured strategies, including connected-host telephony targets, but it must not silently expose a new public surface or send messages to people without a user action.
+
+Agent channel UX should show:
+
+- which channels are enabled by the owning GoodVibes host;
+- whether account/token setup is present without printing secret values;
+- the default target, if configured;
+- delivery risk and public exposure warnings;
+- the command or workspace action needed to pair companion clients through QR-first setup;
+- the confirmed `Send channel message` action when the user explicitly wants a one-off delivery.
+
+Agent-local memory, routines, skills, and personas are not automatically broadcast to channels. External delivery is an effect and requires an exact command, an explicit routine promotion, or a user-approved connected-host request. Companion pairing uses `/pair` without printing the raw token; manual token display requires `/pair --show-token --yes`. One-off delivery uses Agent Workspace -> Channels -> Send channel message or `/channels send ... --yes`.
+
+## Companion And Session Routes
+
+Normal assistant chat uses companion chat routes. Build/fix/review delegation uses shared-session or task routes only when the user explicitly asks for implementation work.
+
+Do not use shared coding sessions for ordinary chat. Do not start background automation for routine assistant work.
+
+## Remote Access
+
+Remote-node and peer capability is owned by the connected GoodVibes host. In Agent, remote commands are read-only unless the user explicitly delegates build/fix/review work to GoodVibes TUI. The current Agent behavior should guide the user toward:
+
+- inspecting remote support state;
+- checking routes and peer readiness;
+- delegating explicit build/fix/review work to GoodVibes TUI when remote execution is actually needed.
+
+Agent should not start remote build hosts, manage peer lifecycle, or fan out separate Agent jobs from the main conversation.
+
+## Public API Use
+
+Use public SDK/operator routes only. For Agent Knowledge, the only valid family is:
+
+```text
+/api/goodvibes-agent/knowledge/*
+```
+
+If an Agent-specific route is missing, fail closed or show guidance. Do not substitute the default knowledge, another product segment, or private connected-host files.
+
+## Related Docs
+
+- [Getting started](getting-started.md)
+- [Knowledge, artifacts, and multimodal](knowledge-artifacts-and-multimodal.md)
+- [Tools and commands](tools-and-commands.md)

package/docs/connected-host.md

@@ -50,10 +50,10 @@ Use the TUI first for those checks:
 
 ## Product Boundary
 
-Agent owns the operator assistant TUI, local profiles, local memory/routines/skills/personas, isolated Agent Knowledge calls, companion chat, approvals/automation visibility, and explicit build delegation.
+Agent owns the operator assistant TUI, local profiles, local memory/notes/routines/skills/personas, isolated Agent Knowledge calls, companion chat, approvals/automation visibility, and explicit build delegation.
 
 Agent does not own connected-host lifecycle. It does not provide commands to install, expose, start, stop, restart, or mutate the connected GoodVibes host.
 
-Agent Knowledge/Wiki is its own product segment. Agent uses `/api/goodvibes-agent/knowledge/*` only and must not fall back to default Knowledge/Wiki or other product-specific knowledge routes.
+Agent Knowledge is its own product segment. Agent uses `/api/goodvibes-agent/knowledge/*` only and must not fall back to default knowledge or other product-specific knowledge routes.
 
-Normal assistant chat uses companion chat. Build/fix/review work is delegated explicitly to GoodVibes TUI through public runtime/session contracts, and WRFC is requested only when explicitly asked for delegated build/fix/review work.
+Normal assistant chat uses companion chat. Build/fix/review work is delegated explicitly to GoodVibes TUI through public runtime/session contracts, and delegated review is requested only when explicitly asked for build/fix/review work.

package/docs/getting-started.md

@@ -40,24 +40,32 @@ bun run dev
 
 `goodvibes-agent` starts the interactive Agent TUI. On a fresh Agent home, the TUI opens Agent setup first.
 
-After setup has been applied once, the TUI opens directly into the Agent operator workspace. You can also reopen it with `/agent`, `/home`, or `/operator`. That fullscreen workspace is the current front door for setup/config, provider/model selection, Agent Knowledge, local memory/skills/routines/personas, channel readiness, voice/media setup, read-only work/approval/automation views, and explicit GoodVibes TUI build delegation.
+After setup has been applied once, the TUI opens directly into the Agent operator workspace. You can also reopen it with `/agent`, `/home`, or `/operator`. That fullscreen workspace is the current front door for setup/config, conversation/session controls, provider/model selection, read-only web research, Agent Knowledge, local memory/notes/skills/routines/personas, channel readiness, voice/media setup, read-only work/approval/automation views, and explicit GoodVibes TUI build delegation.
 
-The setup workspace scans local Agent behavior folders and shows importable persona, skill, and routine files before asking you to create blank records. It can also create one initial local persona, skill, and routine from the setup form. Use `/personas discover`, `/agent-skills discover`, and `/routines discover` to preview files, then use the matching import action in the workspace after review.
+Press `/` inside the Agent workspace to search every workspace action by name, category, command, or detail. Use that finder before reaching for shell commands; CLI subcommands are scriptable mirrors of these TUI workflows.
 
-Use `/agent-profile guide` inside that workspace to walk through starter-profile authoring. It lists built-in and local starters, exports a JSON starter for editing, imports the edited starter back into this Agent home, and creates isolated profiles from the result.
+Use the Artifacts area for concrete files and generated output: attach images to prompts, export conversations or saved sessions, ingest local source files and URL lists into Agent Knowledge, import bookmarks or browser history, inspect source records, and generate media artifacts from confirmed prompts.
+
+The setup workspace scans Agent-local behavior folders and shows importable persona, skill, and routine files before asking you to create blank records. It can also create one initial scratchpad note, local persona, skill, and routine from the setup form. Use the workspace action finder to search for local behavior discovery/import actions, preview files, then import reviewed records from the matching workspace.
+
+Use the Profiles workspace Starter authoring guide to walk through starter-profile authoring. It lists built-in and local starters, exports a JSON starter for editing, imports the edited starter back into this Agent home, and creates isolated profiles from the result.
 
 Use the Profiles workspace form to assemble a local starter template and isolated Agent profile from reviewed discovered persona, skill, and routine files. Scriptable profile commands mirror the same flow for automation; use them only when you intentionally want a shell-driven setup path.
 
-Use the Knowledge area in that workspace to ingest a source URL without leaving the TUI. The form requires typed confirmation and writes only to the isolated Agent Knowledge segment.
+Use the Knowledge area in that workspace to ingest source URLs, local files, URL-list files, bookmarks, browser history, and connector input without leaving the TUI. Every ingest path requires typed confirmation and writes only to the isolated Agent Knowledge segment.
+
+Use the Voice & Media area to review media provider readiness, attach images to conversation prompts, and generate image/video artifacts from a confirmed form. Generated media stays in GoodVibes artifact storage and returns artifact ids for follow-up conversation or delegation; it is not written into default knowledge or non-Agent knowledge segments.
 
 Use the Routines workspace receipt actions to review redacted local routine promotion history and reconcile those receipts with live connected schedules through public `schedules.list`. The `/schedule receipts` and `/schedule reconcile` commands are the power-user equivalents inside the TUI.
 
 The local behavior libraries are configured in the TUI first:
 
-- Memory & Skills -> Create memory or Capture learned behavior.
+- Memory & Skills -> Create memory, Create note, or Capture learned behavior.
+- Notes -> Create note for source triage, temporary decisions, or operator handoff without writing memory or Agent Knowledge.
 - Personas -> Create persona, Use selected, Review selected, or Delete selected.
 - Skills -> Create skill, Create bundle, Enable selected, Review selected, or Delete selected.
-- Routines -> Create routine, Start selected, Enable selected, Promote to schedule, or Review receipts.
+- Routines -> Create routine, Start selected, Enable selected, Promote to schedule, review receipts, or run a confirmed connected schedule.
+- Work -> Add work item, Review work plan, or Update work item status.
 
 The installed CLI mirrors these libraries for scripts, but it is not the primary user workflow.
 
@@ -84,33 +92,39 @@ goodvibes-agent --agent-profile household status
 goodvibes-agent --agent-profile household
 ```
 
-Named profiles isolate Agent-local config, sessions, memory, personas, skills, routines, and setup state under a profile-specific home. `profiles use <name> --yes` makes one profile the default for the next plain `goodvibes-agent` launch; `--agent-profile <name>` still overrides it for one launch, and `profiles default clear --yes` returns plain launches to the base Agent home. Starter templates seed local personas, skills, and routines for household, research, travel, operations, and personal productivity profiles; exported starter JSON can be edited and re-imported as a local starter. They do not start or isolate the connected host by themselves.
+Named profiles isolate Agent-local config, sessions, memory, notes, personas, skills, routines, and setup state under a profile-specific home. `profiles use <name> --yes` makes one profile the default for the next plain `goodvibes-agent` launch; `--agent-profile <name>` still overrides it for one launch, and `profiles default clear --yes` returns plain launches to the base Agent home. First-run setup seeds new profiles from a built-in starter by default unless you explicitly choose `No profile`. Starter templates seed local personas, skills, and routines for household, research, travel, operations, and personal productivity profiles; exported starter JSON can be edited and re-imported as a local starter. They do not start or isolate the connected host by themselves.
 
 ## Local Memory, Personas, Routines, And Skills
 
-Memory, personas, routines, and reusable Agent skills are local to GoodVibes Agent. First-run setup, TUI workspace forms, and CLI commands all write them to Agent-local registries. They do not write into default Knowledge/Wiki or non-Agent knowledge segments.
+Memory, notes, personas, routines, and reusable Agent skills are local to GoodVibes Agent. First-run setup, TUI workspace forms, and CLI commands all write them to Agent-local registries. They do not write into default knowledge or non-Agent knowledge segments.
 
 Use `Capture learned behavior` in the Agent workspace after reviewing a repeated workflow, lesson, or operating style. It saves one local skill, routine, or persona from the TUI and does not call connected-host mutation routes.
 
+Use Agent Workspace -> Research for web research and URL inspection. Research requests run in the normal main conversation, can use connected read-only web tools when you ask, and do not ingest sources. Use confirmed Agent Knowledge ingest actions only when a reviewed source should become durable Agent-owned knowledge.
+
+Use Agent Workspace -> Notes for source triage and temporary context. Notes are a scratchpad: they are reviewable local records, but they do not become durable memory or Agent Knowledge unless you explicitly promote them into memory/skills/routines/personas or run a confirmed Agent Knowledge ingest action. A reviewed note with a source URL can prefill the Agent Knowledge URL ingest form so you do not have to copy the URL by hand.
+
 Day-one local behavior setup should stay in the fullscreen workspace:
 
 - Personas -> Create persona, then Use selected.
 - Routines -> Create routine, Start selected, or Promote to schedule after entering real timing and confirmation.
 - Skills -> Create skill, Enable selected, and review setup requirements.
-- Memory & Skills -> Create memory or Search memory.
-- Channels -> inspect readiness before enabling notification delivery.
+- Memory & Skills -> Create memory, Create note, or Search memory.
+- Channels -> inspect readiness, send one explicit channel delivery message, add notification targets, and send notification messages only through confirmed actions.
 
 Typed slash commands are available for repeat users, but they are not required for the first-run workflow.
 
-The active persona plus enabled Agent routines, reviewed memory, and skills are injected into the main serial assistant conversation. Starting a routine records local usage and prints its steps; it does not launch local workers or automation jobs. Promoting a routine to a schedule is an explicit `schedules.create` call, requires `--yes`, writes a local redacted promotion receipt, and preserves the rule that Agent Knowledge never falls back to default Knowledge/Wiki or non-Agent knowledge segments.
+The active persona plus enabled Agent routines, reviewed memory, and skills are injected into the main serial assistant conversation. Starting a routine records local usage and prints its steps in the main conversation; it does not start background automation. Promoting a routine to a schedule is an explicit `schedules.create` call, requires `--yes`, writes a local redacted promotion receipt, and preserves the rule that Agent Knowledge never falls back to default knowledge or non-Agent knowledge segments.
+
+Use `/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.
 
-Use `/channels` inside the TUI for a read-only channel readiness matrix. It shows enabled channels, missing config key names, delivery posture, and risk labels without sending messages or rendering token values.
+The main assistant conversation can perform narrow confirmed operator actions when the user explicitly asks for a specific target: approve/deny/cancel one approval, run/pause/resume one automation job, cancel/retry one automation run, or run one schedule. Those calls use only public connected-host routes, require confirmation, and do not create, edit, or delete automation definitions.
 
 ## Connected GoodVibes Host
 
 Start the owning GoodVibes host before using connected Agent features. Agent expects that host to expose the public operator/Agent routes, including:
 
-- `/status`
+- `GET /status`
 - `/api/goodvibes-agent/knowledge/status`
 - `/api/goodvibes-agent/knowledge/ask`
 - `/api/goodvibes-agent/knowledge/search`
@@ -118,10 +132,10 @@ Start the owning GoodVibes host before using connected Agent features. Agent exp
 
 If the GoodVibes API is not on `http://127.0.0.1:3421`, pass `--runtime-url http://host:port` for a one-off TUI launch or set `GOODVIBES_AGENT_RUNTIME_URL=http://host:port` before launching the TUI.
 
-Agent Knowledge/Wiki is an Agent-owned product segment. Agent commands must not fall back to default Knowledge/Wiki or other product-specific knowledge spaces.
+Agent Knowledge is an Agent-owned product segment. Agent commands must not fall back to default knowledge or other product-specific knowledge spaces.
 
 Host lifecycle commands are not part of GoodVibes Agent. Use Agent Workspace -> Home -> Host compatibility, Doctor diagnostics, and Review health for diagnostics. CLI status/doctor/compat commands are scriptable mirrors for install checks.
 
 ## Current Product Notes
 
-Agent uses the mature GoodVibes terminal shell, renderer, input, fullscreen workspace, command registry, and release foundation. The active Agent policy is serial/proactive by default, blocks local Agent-owned WRFC/spawn fanout, and delegates explicit build/fix/review work to GoodVibes TUI instead of turning the Agent into a coding TUI.
+Agent uses the mature GoodVibes terminal shell, renderer, input, fullscreen workspace, command registry, and release foundation. The active Agent policy is serial/proactive by default, blocks Agent-owned review/job fanout, and delegates explicit build/fix/review work to GoodVibes TUI instead of turning the Agent into a coding TUI.

package/docs/knowledge-artifacts-and-multimodal.md

@@ -0,0 +1,91 @@
+# Knowledge, Artifacts, and Multimodal
+
+GoodVibes Agent has its own Knowledge segment. It must not query or ingest through default knowledge or other product-specific knowledge spaces.
+
+## Context Layers
+
+GoodVibes Agent uses these context layers:
+
+- current conversation context for the active turn;
+- Agent-local memory records for durable but private assistant facts and preferences;
+- Agent-local routines, skills, and personas for reusable behavior profiles;
+- isolated Agent Knowledge for source-backed documents, search, and semantic answers;
+- artifacts for uploaded/generated files that can be referenced by chat, delegation, or explicit Agent Knowledge ingestion.
+
+These layers are intentionally separate. Local memory/routines/skills/personas are not automatically promoted into Agent Knowledge. Agent Knowledge records are not copied into default knowledge. Secrets are rejected or represented only by explicit secret references.
+
+## Agent Knowledge Boundary
+
+Agent Knowledge uses only the Agent route family:
+
+```text
+GET  /api/goodvibes-agent/knowledge/status
+POST /api/goodvibes-agent/knowledge/ask
+POST /api/goodvibes-agent/knowledge/search
+GET  /api/goodvibes-agent/knowledge/sources
+GET  /api/goodvibes-agent/knowledge/nodes
+GET  /api/goodvibes-agent/knowledge/issues
+GET  /api/goodvibes-agent/knowledge/items/{id}
+GET  /api/goodvibes-agent/knowledge/connectors
+POST /api/goodvibes-agent/knowledge/ingest/url
+POST /api/goodvibes-agent/knowledge/ingest/urls
+POST /api/goodvibes-agent/knowledge/ingest/bookmarks
+POST /api/goodvibes-agent/knowledge/reindex
+```
+
+If those routes are unavailable, Agent commands fail closed with a structured error. They do not retry against the default knowledge routes or arbitrary knowledge-space selectors.
+
+The CLI and slash-command layers reject route-selection flags such as `--space`, `--knowledge-space`, `--knowledge-space-id`, and `--include-all-spaces` because those would violate the Agent product boundary.
+
+Agent Knowledge writes are explicit-user-action paths. Slash commands that ingest, import, review issues, reindex, or run consolidation require `--yes`; ask/search/status/list paths remain read-only.
+
+## Ask And Search
+
+Use Agent Workspace -> Knowledge -> Ask Agent knowledge for source-backed Agent Knowledge answers. `/knowledge ask <query>` and `goodvibes-agent ask <query>` are scriptable equivalents over the same route. Default output is concise:
+
+- answer text or a clear no-match state;
+- confidence when present;
+- sources, titles, and URLs when returned;
+- facts, gaps, and refinement task ids only when the Agent Knowledge route returns them.
+
+`--json` preserves the raw structured Agent route response for tooling.
+
+The command layer does not turn search results into an answer locally and does not apply client-side filters to hide contamination. Isolation must come from the Agent Knowledge route itself.
+
+Use Agent Workspace -> Knowledge -> Search Agent knowledge for interactive search. `/knowledge search <query>` and `goodvibes-agent search <query>` query the isolated Agent Knowledge search route and render bounded results with title, id, type, score, source, URL, and snippets when available. Empty Agent stores return an explicit empty state.
+
+Read-only inspection is available from the TUI Knowledge workspace first, with CLI equivalents for scripts:
+
+- Source library and review queue in Agent Workspace -> Knowledge.
+- `/knowledge list --kind sources|nodes|issues`
+- `/knowledge get <id>`
+- `/knowledge connectors`
+- `/knowledge map`
+
+## Ingest
+
+Use Agent Workspace -> Knowledge for URL, URL-list, file, bookmark, browser-history, connector ingest, and reindex forms. The main assistant conversation can also call the confirmed `agent_knowledge_ingest` tool for the same isolated source families. `/knowledge ingest-url <url> --yes` and `goodvibes-agent knowledge ingest-url <url> --yes` ingest URL sources into Agent Knowledge only.
+
+The TUI workspace exposes the common confirmed ingest and reindex flows. The CLI also exposes Agent-specific batch routes for scripts:
+
+- `goodvibes-agent knowledge import-urls <path> --yes`
+- `goodvibes-agent knowledge import-bookmarks <path> --yes`
+- `goodvibes-agent knowledge reindex --yes`
+
+All of these commands target `/api/goodvibes-agent/knowledge/*`; none of them call default knowledge.
+
+Do not map local memory, notes, routines, skills, personas, or default knowledge documents into Agent Knowledge automatically. Durable source-backed facts can be ingested deliberately through Agent routes when the user or an explicit Agent workflow asks for it.
+
+## Artifacts And Multimodal
+
+Artifacts are first-class runtime objects for files, images, audio, video, generated outputs, and delegation results. Agent Knowledge use of artifacts must still go through Agent-specific ingest routes when those are available.
+
+Agent Workspace -> Voice & Media -> Generate media creates image/video artifacts through configured media providers after typed confirmation. The main conversation can perform the same confirmed action with the `agent_media_generate` tool when the user explicitly asks for generated media. Generated media output is summarized as artifact ids, MIME types, filenames, and source URLs when present; inline base64 is not printed into the transcript.
+
+Until dedicated Agent artifact-ingest route coverage exists, multimodal outputs should stay in the conversation, artifacts, local notes or memory, or explicit delegation results rather than being inserted into default knowledge.
+
+## Related Docs
+
+- [Tools and commands](tools-and-commands.md)
+- [Getting started](getting-started.md)
+- [Release and publishing](release-and-publishing.md)

package/docs/project-planning.md

@@ -0,0 +1,79 @@
+# Project Planning
+
+GoodVibes Agent owns the active planning loop for operator work. Planning is part of the Agent main conversation, not a hidden execution flow and not a default knowledge query.
+
+## Boundary
+
+The Agent owns:
+
+- natural-language planning intent detection in the main terminal conversation;
+- one-question-at-a-time clarification;
+- the Agent-owned planning loop;
+- transcript-first planning summaries and the Agent operator workspace planning state;
+- explicit execution approval;
+- delegation metadata when work needs GoodVibes TUI.
+
+The SDK/runtime owns durable storage and route contracts:
+
+- planning namespaces such as `project:<projectId>`;
+- readiness evaluation and next-question hints;
+- decision records;
+- task, dependency, verification, and assignment metadata;
+- passive operator methods.
+
+Other surfaces can store or inspect planning artifacts, but conversation control stays in Agent. Agent planning state is not default knowledge, another product segment, or arbitrary knowledge data.
+
+## Agent Behavior
+
+The Agent derives a stable `projectId` from the workspace path and passes it to the SDK planning service. Planning artifacts are stored under the matching planning namespace so unrelated workspaces do not share state.
+
+Normal conversation can start planning when the user asks for an execution strategy, dependency graph, verification gates, or delegation handoff. The Agent then:
+
+- prints a concise planning summary in the main transcript;
+- persists the current planning state through public SDK/runtime seams;
+- records active open questions and user answers;
+- calls readiness evaluation for gaps and the suggested next question;
+- asks one focused question instead of executing prematurely.
+
+The planning loop can be paused with natural language such as "stop planning" or "pause planning".
+
+## Planning View
+
+The planning view is transcript-first today. It shows:
+
+- workspace project id and planning namespace;
+- readiness and approval state;
+- goal, scope, known context, and current next question;
+- blocking or advisory readiness gaps;
+- task graph and verification gates;
+- delegation candidates;
+- durable decisions;
+- project language and ambiguity resolutions.
+
+Keyboard behavior stays in the main Agent TUI: predictable prompt editing, scroll, submit, dismiss, and return-to-chat behavior.
+
+## `/plan`
+
+`/plan` remains a command workspace for inspection and seeding:
+
+- `/plan` prints current planning readiness and the next planning question;
+- `/plan panel` is guidance-only in Agent and points back to `/plan status` or `/plan list`;
+- `/plan approve` records explicit execution approval;
+- `/plan <goal>` seeds Agent workspace planning state;
+- `/plan list` and `/plan show <id>` inspect older execution-plan records.
+
+Use natural language such as "pause planning" or "stop planning" when planning should pause and normal chat should continue.
+
+## Work Plan
+
+The work-plan tracker is for concrete, durable task state after work becomes actionable. It is separate from the planning interview loop.
+
+Use `/workplan` when the work already has tasks and needs status tracking. Use `/delegate` when explicit build/fix/review work should go to GoodVibes TUI.
+
+## Agent Knowledge Boundary
+
+Planning may link to Agent Knowledge evidence, but it must not query or ingest through default knowledge. Source-backed facts for Agent belong under:
+
+```text
+/api/goodvibes-agent/knowledge/*
+```

package/docs/providers-and-routing.md

@@ -0,0 +1,46 @@
+# Providers and Routing
+
+GoodVibes Agent uses the provider/model configuration exposed by the connected GoodVibes host. The Agent TUI should make the active route easy to see and easy to change, but it should not duplicate provider hosting logic.
+
+## Agent Expectations
+
+Provider and model state should be visible in:
+
+- the shell footer/status rows;
+- `/health` in the TUI and `goodvibes-agent status` in the CLI;
+- `/model` and `/provider`;
+- the Agent operator workspace setup checklist;
+- the TTS configuration workspace when spoken turns are used.
+
+When a selected model is provider-qualified, Agent keeps the runtime provider row and raw model id separate. For example, `openai-subscriber` plus `openai:gpt-5.5` should route as provider `openai-subscriber` and model `gpt-5.5` where the public route expects provider/model fields.
+
+## Local Provider Definitions
+
+Agent-owned provider definitions live under the Agent profile root when supported by the shared GoodVibes provider registry:
+
+```text
+~/.goodvibes/agent/providers/*.json
+```
+
+These files are local configuration. They are not Agent Knowledge records and should not be copied into knowledge search state.
+
+## Discovery And Health
+
+Provider discovery and health are owned by the connected GoodVibes host. Agent can display discovered provider status, model context information, and route failures. It should not hide provider failures behind fallback wording that makes a failed chat or knowledge request look successful.
+
+## Search, Voice, And Media Providers
+
+Search, voice, media, and multimodal providers are valid Agent features when they are presented as assistant workflows:
+
+- research and source lookup;
+- live spoken turns;
+- image/document analysis;
+- artifact creation and review.
+
+Outputs that should become durable knowledge must go through Agent Knowledge routes. No provider output should be inserted into default knowledge or another product segment by Agent.
+
+## Related Docs
+
+- [Getting started](getting-started.md)
+- [Knowledge, artifacts, and multimodal](knowledge-artifacts-and-multimodal.md)
+- [Voice and live TTS](voice-and-live-tts.md)

package/docs/release-and-publishing.md

@@ -7,8 +7,9 @@ GoodVibes Agent's current installable public alpha version is recorded in `packa
 - registry package: `@pellux/goodvibes-agent`
 - executable: `goodvibes-agent`
 - SDK dependency: exact pin to `@pellux/goodvibes-sdk@0.33.35`
-- runtime: Bun
+- runtime: Bun `1.3.10` or newer
 - source language: TypeScript
+- package docs: every Markdown file under `docs/*.md`
 - connected host ownership: outside Agent
 
 End users install and run GoodVibes Agent with Bun:
@@ -18,7 +19,7 @@ bun add -g @pellux/goodvibes-agent
 goodvibes-agent --help
 ```
 
-Do not add non-Bun install instructions for this product. The package is hosted on the public package registry, but the supported install and smoke path is the normal Bun global command above, followed by `goodvibes-agent` launching the TUI.
+Do not add non-Bun install instructions for this product. The package is hosted on the public package registry, but the supported install and smoke path is the normal Bun global command above, followed by `goodvibes-agent` launching the TUI. The package-facing text policy rejects non-Bun Agent install/run snippets, references to other `@pellux/goodvibes-*` packages outside Agent and the SDK, and versioned Agent or SDK package references that drift from `package.json`.
 
 ## Required Gates
 
@@ -34,36 +35,70 @@ bun pm pack --dry-run
 git diff --check
 ```
 
-`bun run publish:package` publishes from a staged package directory to the package registry. 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 `publish:check` to keep release metadata and package-facing text checks, package runtime build, npm pack dry-run, forbidden/required tarball path assertions, and the tarball size cap before reporting success.
 
-`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. Release notes should describe what changed for Agent users: TUI behavior, setup, Agent Knowledge, local behavior libraries, connected-host compatibility, package/install behavior, and safety policy. Do not use commit hashes as the shipped changelog content.
+Shared release metadata verification also requires `build:package-runtime` to keep the clean `dist/package/main.js` build, Bun compile compatibility patch, build-machine path-leak guards, empty-entrypoint guard, and runtime build success summary.
 
-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.
+Shared release metadata verification requires `scripts/bun-compile-compat.ts` to keep the css-tree JSON-import rewrites, jsdom XHR worker and stylesheet path-leak patches, sql.js wasm embedding, idempotent patch skip, unexpected-shape warning, and successful patch diagnostic that keep Bun-compiled Agent runtimes self-contained.
 
-Branch CI is the only workflow that runs the full test suite and release gates. It runs `bun run test` once for the release SHA, along with typecheck, architecture, performance, build, publish, and packed install checks. The release workflow must not run tests or duplicate those gates; it verifies that branch CI passed for the exact checked-out SHA and then performs only package packing, GitHub Release creation, and optional npm publish.
+Shared release metadata verification requires the `prebuild` and `version` package scripts to run `scripts/prebuild.ts`; that script must keep the workspace-locked project-surface sync and Bun compile compatibility patch, while `scripts/project-surfaces.ts` must preserve exact semver reads plus `src/version.ts` and README badge synchronization.
+
+`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. The 1.0 release candidate uses `--notes-file release/1.0-release-notes.md`, and release metadata verification requires that artifact to exist, contain product-facing notes, and be staged 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, 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.
+
+`--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 the 1.0 cut, preview with `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`.
+
+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.
+
+Branch CI is the only workflow that runs the full test suite and release gates. It runs `bun run test` once for the release SHA, along with typecheck, architecture, performance, build, publish, packed install, and verification ledger checks. The release workflow must not run tests or duplicate those gates; shared release metadata verification rejects duplicated release-workflow gates and requires the workflow to verify that branch CI and its test job passed for the exact checked-out SHA before package packing, GitHub Release creation, and optional npm publish. It also requires the release workflow to preserve tag/package version matching, single-tarball packing, changelog excerpt extraction, and GitHub Release tarball attachment markers.
+
+Shared release metadata verification requires the package build scripts to keep exact TypeScript and Bun compile commands for the Agent entrypoint and platform binary names. It also requires `scripts/build.ts` to keep the prebuild/compatibility patch, multi-target matrix, sqlite-vec native addon externalization/copy policy, same-platform hard failure, cross-target warning, and build summary/failure exit behavior.
+
+Shared release metadata verification requires branch CI to run the compiled binary smoke after `bun run build`, and `scripts/post-build-smoke.ts` must keep the default `dist/goodvibes-agent` binary path, optional `--binary` override, isolated temp cwd, `--version` launch, sqlite-vec/`$bunfs` module-resolution leak guards, Agent version-prefix assertion, failure diagnostics, and cleanup.
+
+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 `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:live` to keep the external-outcome audit for release candidates: 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.
 
 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.
 
+Shared release metadata verification requires the `test` script to keep using `scripts/run-tests.ts`, and that runner must discover all `.test`/`.spec` TypeScript files under `src`, sort them deterministically, run one `bun test` invocation with an isolated `.test-tmp/suite` temp root, fail when no tests are found, and propagate the Bun test exit code.
+
 Also run the package install smoke from a packed artifact. It must prove:
 
 - the installed command is on `PATH`
 - the bin target is `bin/goodvibes-agent.ts`
 - the Bun shebang survives pack/install
 - the bundled runtime `dist/package/main.js` is present and non-empty
+- every shared required package path is installed as a non-empty file
+- every package-facing `docs/*.md` page is installed and non-empty
 - Bun global install uses `bun add -g`
 - `goodvibes-agent --help` works
 - `goodvibes-agent --version` reports the package version
 - the installed TUI launches in a PTY and does not exit immediately
 - connected-host commands fail clearly when GoodVibes host is unavailable or unauthenticated
-- no token value is printed
+- a seeded connected-host token sentinel is never printed in captured command output, PTY transcript, or failure diagnostics
+
+Shared release metadata verification requires the install-check script to keep those packed artifact, Bun global install, installed CLI/status, blocked lifecycle command, PTY launch, required-path, runtime, token-sentinel, and cleanup markers.
 
 ## Do Not Ship
 
 Do not publish if package-facing docs or install commands refer to another package name, another executable, or Agent-owned connected-host lifecycle.
 
-Do not publish if Agent Knowledge commands can fall back to default Knowledge/Wiki or another product-specific knowledge route. Agent Knowledge must use the isolated `/api/goodvibes-agent/knowledge/*` segment.
+Do not publish if `README.md` or `docs/README.md` omits a package-facing docs page, or links a docs page that is not included by the package `files` manifest.
+
+Do not publish if Agent Knowledge commands can fall back to default knowledge or another product-specific knowledge route. Agent Knowledge must use the isolated `/api/goodvibes-agent/knowledge/*` segment.
 
-Do not ship GoodVibes service binaries from this package. If Agent later gets compiled artifacts, they must use Agent artifact names and remain separate from connected-host ownership.
+Do not ship connected-host binaries from this package. If Agent later gets compiled artifacts, they must use Agent artifact names and remain separate from connected-host ownership.
 
 ## Product Rule