@pellux/goodvibes-agent 0.1.116 → 1.0.0

package/docs/README.md

@@ -5,22 +5,29 @@ These are the package-facing docs for GoodVibes Agent, the personal operator ass
 Current package docs:
 
 - [Getting Started](getting-started.md)
-- [Connected Services](connected-services.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 GoodVibes services owned outside this product.
-- Agent does not start, stop, restart, install, uninstall, or own those connected GoodVibes services.
-- Agent Knowledge/Wiki uses only `/api/goodvibes-agent/knowledge/*`; there is no default Knowledge/Wiki or non-Agent product fallback.
+- 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 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-service URL overrides with `--runtime-url http://host:port` or `GOODVIBES_AGENT_RUNTIME_URL=http://host:port`; these only change the Agent connection target.
+- 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.
-- 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

@@ -0,0 +1,59 @@
+# Connected Host
+
+GoodVibes Agent is a TUI client for a connected GoodVibes host owned outside this package. The package exposes one executable:
+
+```sh
+goodvibes-agent
+```
+
+The installed command is backed by TypeScript-authored source with a Bun shebang. Package install smoke verifies the executable path:
+
+- `goodvibes-agent --help`
+- `goodvibes-agent --version`
+- `goodvibes-agent status --json`
+- `goodvibes-agent` launches the TUI in a real PTY
+
+## Host Prerequisite
+
+Start the owning GoodVibes host before launching Agent. Agent expects that host to expose public operator routes and the isolated Agent Knowledge routes:
+
+```text
+http://127.0.0.1:3421
+/api/goodvibes-agent/knowledge/status
+/api/goodvibes-agent/knowledge/ask
+/api/goodvibes-agent/knowledge/search
+```
+
+If the GoodVibes API is on a different host or port, use a one-off override when launching the TUI:
+
+```sh
+goodvibes-agent --runtime-url http://127.0.0.1:3421
+```
+
+For a persistent shell/session override, set:
+
+```sh
+export GOODVIBES_AGENT_RUNTIME_URL=http://127.0.0.1:3421
+```
+
+`GOODVIBES_AGENT_BASE_URL` is accepted as a legacy alias. These values only select the connected GoodVibes API root; they do not make Agent own host processes.
+
+If the connected host is unavailable, unauthenticated, or on an incompatible SDK version, the Agent TUI reports actionable diagnostics without printing token values.
+
+Use the TUI first for those checks:
+
+- Agent Workspace -> Home -> Host compatibility
+- Agent Workspace -> Home -> Doctor diagnostics
+- Agent Workspace -> Home -> Review health
+
+`goodvibes-agent status --json`, `goodvibes-agent doctor`, and `goodvibes-agent compat` are scriptable equivalents for install checks and automation.
+
+## Product Boundary
+
+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 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 delegated review is requested only when explicitly asked for build/fix/review work.

package/docs/getting-started.md

@@ -5,12 +5,12 @@ GoodVibes Agent is the installable public alpha of the personal operator assista
 ## Requirements
 
 - Bun `1.3.10` or newer
-- Connected GoodVibes services compatible with `@pellux/goodvibes-sdk@0.33.35`
-- A token/config path accepted by connected GoodVibes services
+- A connected GoodVibes host compatible with `@pellux/goodvibes-sdk@0.33.35`
+- A token/config path accepted by the connected host
 
-Agent does not launch connected GoodVibes services for you.
+Agent does not launch the connected host for you.
 
-Use the interactive TUI first. CLI subcommands are secondary support paths for install checks, setup inspection, and scriptable local Agent libraries.
+Use the interactive TUI first. CLI subcommands are secondary support paths for install checks, setup inspection, and scriptable mirrors of workflows that are already reachable from the workspace.
 
 ## Install From Package
 
@@ -18,10 +18,6 @@ Use the interactive TUI first. CLI subcommands are secondary support paths for i
 bun add -g @pellux/goodvibes-agent
 goodvibes-agent --help
 goodvibes-agent
-goodvibes-agent status
-goodvibes-agent personas list
-goodvibes-agent skills list
-goodvibes-agent memory list
 ```
 
 If the installed command is not found, add Bun's global bin directory to `PATH`:
@@ -44,87 +40,102 @@ 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 shown 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. 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.
 
-Use `goodvibes-agent profiles create-from-discovered research-desk --yes` or the Profiles workspace form to assemble a local starter template and isolated Agent profile from reviewed discovered persona, skill, and routine files. Use `profiles templates from-discovered <id> --yes` only when you want to save the starter before creating a profile.
+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 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 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 `/schedule receipts` to review redacted local routine promotion history and `/schedule reconcile` to compare those receipts with live connected schedules through public `schedules.list`.
+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.
 
-The local behavior libraries are also available from the installed CLI:
+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.
 
-```sh
-goodvibes-agent personas create --name "Research Analyst" --description "Source-backed research" --body "Check sources and call out uncertainty" --use
-goodvibes-agent skills create --name "Morning Brief" --description "Daily briefing flow" --procedure "Check tasks, approvals, routines, and Agent Knowledge before summarizing" --enabled
-goodvibes-agent memory add fact "Prefers concise morning briefings" --scope project --tags preference
-goodvibes-agent routines list
-```
+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, Create note, or Capture learned behavior.
+- Notes -> Create note for source triage, temporary decisions, or operator handoff without writing memory or Agent Knowledge.
+- Personas -> Create persona, Use selected, Review selected, or Delete selected.
+- Skills -> Create skill, Create bundle, Enable selected, Review selected, or Delete selected.
+- Routines -> Create routine, Start selected, Enable selected, Promote to schedule, review receipts, or run a confirmed connected schedule.
+- Work -> Add work item, Review work plan, or Update work item status.
+
+The installed CLI mirrors these libraries for scripts, but it is not the primary user workflow.
 
 ## Isolated Agent Profiles
 
-Use a separate Agent home when you want isolated local state:
+Use a separate Agent home when you want isolated local state. The normal launch still opens the TUI:
 
 ```sh
-GOODVIBES_AGENT_HOME=/path/to/agent-home goodvibes-agent status
+GOODVIBES_AGENT_HOME=/path/to/agent-home goodvibes-agent
 ```
 
-Use named Agent profiles for repeatable local identities:
+Use named Agent profiles for repeatable local identities from Agent Workspace -> Profiles. The workspace can browse starter templates, create isolated Agent profiles, set or clear the default profile for the next launch, and export/import starter JSON.
+
+Scriptable equivalents for automation and setup scripts:
 
 ```sh
 goodvibes-agent profiles templates
 goodvibes-agent profiles create household --template household --yes
+goodvibes-agent profiles use household --yes
+goodvibes-agent
 goodvibes-agent profiles templates export research ./research-starter.json --yes
 goodvibes-agent profiles templates import ./research-starter.json --yes
 goodvibes-agent --agent-profile household status
 goodvibes-agent --agent-profile household
 ```
 
-Named profiles isolate Agent-local config, sessions, memory, personas, skills, routines, and setup state under a profile-specific 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 connected GoodVibes services 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. They do not write into default Knowledge/Wiki or non-Agent knowledge segments.
-
-```text
-/personas list
-/personas create --name Research --description "Source-backed research" --body "Check sources, call out uncertainty, keep answers concise."
-/personas use research
-/routines create --name "Evening Review" --description "Review open work before shutdown" --steps "Check work plan, approvals, and Agent Knowledge status before summarizing." --enabled true
-/routines start evening-review
-/schedule promote-routine evening-review --cron "0 17 * * 1-5" --timezone America/Chicago --yes
-/channels
-/agent-skills create --name "Morning Brief" --description "Daily briefing flow" --procedure "Check tasks, approvals, calendar, and unread state before summarizing." --enabled true
-/agent-skills enabled
-/skills list
-/memory add fact "Prefers concise morning briefings" --scope project --tags preference
-/memory search morning
-```
+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, 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 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.
 
-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 spawn background agents 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.
+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 Services
+## Connected GoodVibes Host
 
-Start connected GoodVibes services from GoodVibes TUI or the owning host before using service-backed Agent features. Agent expects those services to expose the public operator/Agent routes, including:
+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`
 - `/api/goodvibes-agent/knowledge/ingest/url`
 
-If the GoodVibes API is not on `http://127.0.0.1:3421`, use `goodvibes-agent --runtime-url http://host:port status` for a one-off check or set `GOODVIBES_AGENT_RUNTIME_URL=http://host:port` before launching the TUI.
+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.
 
-Service-hosting commands are not part of GoodVibes Agent. Use `goodvibes-agent status`, `goodvibes-agent doctor`, and the Agent TUI status views for diagnostics.
+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)