@pellux/goodvibes-agent 0.1.116 → 1.0.0

package/docs/release-and-publishing.md

@@ -7,9 +7,10 @@ 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
-- connected services ownership: outside Agent
+- 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,34 +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.
 
-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 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.
 
-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 `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.
+
+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-service commands fail clearly when GoodVibes services are unavailable or unauthenticated
-- no token value is printed
+- connected-host commands fail clearly when GoodVibes host is unavailable or unauthenticated
+- 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-service lifecycle.
+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 `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/Wiki or another product-specific knowledge route. Agent Knowledge must use the isolated `/api/goodvibes-agent/knowledge/*` segment.
+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-service 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
 

package/docs/tools-and-commands.md

@@ -0,0 +1,123 @@
+# 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.
+
+## Product 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 until a stable shared registry contract exists.
+- 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.
+
+## TUI-First Operator Surface
+
+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 Agent TUI paths:
+
+- `/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.
+- `/approvals` 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.
+
+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.
+
+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.
+
+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.
+
+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.
+
+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`.
+
+## 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)

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

@@ -0,0 +1,51 @@
+# Voice and Live TTS
+
+GoodVibes Agent supports spoken turns as an Agent TUI feature. Text output remains primary; voice is an additional local playback path for a normal assistant turn.
+
+## Commands
+
+```text
+/tts <prompt>
+/tts stop
+/config tts
+/config tts.provider
+/config tts.voice
+/config tts.llmProvider
+/config tts.llmModel
+```
+
+`/tts <prompt>` submits the prompt through the normal Agent conversation path. It uses the active chat provider/model unless a separate spoken-turn model override is configured.
+
+`/tts stop` cancels queued spoken output and active playback without cancelling the text transcript.
+
+`/config tts` opens the fullscreen configuration workspace for streaming provider, voice, and spoken-turn model routing.
+
+## Playback Requirements
+
+Live playback streams audio to a local player. Install one of:
+
+- `mpv`;
+- `ffplay`.
+
+If neither player is on `PATH`, the Agent still submits and renders the normal text response. Audio is skipped with a concise status message.
+
+## Provider Routing
+
+Voice uses providers that advertise streaming TTS capability through the runtime. Agent does not hardcode provider behavior.
+
+Useful setup path:
+
+```text
+/config tts.provider
+/config tts.voice
+/config tts.llmProvider
+/config tts.llmModel
+```
+
+Leaving `tts.voice` empty lets the provider choose its default voice.
+
+## Knowledge Boundary
+
+Spoken responses are conversation output. They are not automatically written to Agent Knowledge, local memory, default knowledge, or any other product segment.
+
+If a spoken result should become durable, store it through an explicit Agent memory command or an Agent Knowledge ingestion path.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-agent",
-  "version": "0.1.116",
+  "version": "1.0.0",
   "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",
@@ -17,14 +17,12 @@
     "!src/test",
     "!src/**/*.test.ts",
     "!src/**/__tests__",
+    "!src/cli/package-verification.ts",
     "!src/verification",
     "tsconfig.json",
     "README.md",
     "CHANGELOG.md",
-    "docs/README.md",
-    "docs/getting-started.md",
-    "docs/connected-services.md",
-    "docs/release-and-publishing.md"
+    "docs/*.md"
   ],
   "scripts": {
     "dev": "bun run src/main.ts",
@@ -54,7 +52,6 @@
     "build:all": "bun run scripts/build.ts --all",
     "perf:check": "bun run scripts/perf-check.ts",
     "architecture:check": "bun run scripts/check-architecture.ts",
-    "foundation:artifacts": "bun run scripts/export-foundation-artifacts.ts",
     "verification:ledger": "bun run scripts/verification-ledger.ts",
     "verification:live": "bun run scripts/verify-live.ts"
   },

package/src/agent/behavior-discovery-summary.ts

@@ -126,12 +126,10 @@ function definitions(shellPaths: Pick<ShellPathService, 'workingDirectory' | 'ho
     roots: [
       { root: join(cwd, '.goodvibes', 'personas'), origin: 'project-local' },
       { root: join(cwd, '.goodvibes', GOODVIBES_AGENT_SURFACE_ROOT, 'personas'), origin: 'project-local' },
-      { root: join(cwd, '.goodvibes', 'agents'), origin: 'project-local' },
       { root: join(homeDir, '.goodvibes', 'personas'), origin: 'global' },
       { root: join(homeDir, '.goodvibes', GOODVIBES_AGENT_SURFACE_ROOT, 'personas'), origin: 'global' },
-      { root: join(homeDir, '.goodvibes', 'agents'), origin: 'global' },
     ],
-    markers: ['PERSONA.md', 'persona.md', 'AGENT.md', 'agent.md'],
+    markers: ['PERSONA.md', 'persona.md'],
     frontmatterBodyKey: 'system_prompt',
   };
   const skills: DiscoveryKindDefinition = {

package/src/agent/channel-delivery.ts

@@ -0,0 +1,201 @@
+import type {
+  ChannelDeliveryRequest,
+  ChannelDeliveryRouter,
+  ChannelDeliverySurfaceKind,
+  ChannelDeliveryTarget,
+} from '@pellux/goodvibes-sdk/platform/channels';
+
+type AgentChannelDeliveryRouter = Pick<ChannelDeliveryRouter, 'deliver' | 'listStrategies'>;
+type AgentChannelDeliverySurfaceKind = ChannelDeliverySurfaceKind | 'telephony';
+type AgentChannelDeliveryTarget = Omit<ChannelDeliveryTarget, 'surfaceKind'> & {
+  readonly surfaceKind?: AgentChannelDeliverySurfaceKind;
+};
+type AgentChannelDeliveryRequest = Omit<ChannelDeliveryRequest, 'target'> & {
+  readonly target: AgentChannelDeliveryTarget;
+};
+
+export interface AgentChannelDeliveryInput {
+  readonly message: string;
+  readonly title?: string;
+  readonly channel?: string;
+  readonly route?: string;
+  readonly webhook?: string;
+  readonly link?: string;
+}
+
+export interface AgentChannelDeliveryPreview {
+  readonly message: string;
+  readonly title: string;
+  readonly target: AgentChannelDeliveryTarget;
+  readonly request: AgentChannelDeliveryRequest;
+}
+
+export interface AgentChannelDeliveryResult {
+  readonly responseId?: string;
+  readonly message: string;
+  readonly title: string;
+  readonly target: AgentChannelDeliveryTarget;
+  readonly strategyCount: number;
+}
+
+const DELIVERY_SURFACE_KINDS: readonly AgentChannelDeliverySurfaceKind[] = [
+  'tui',
+  'web',
+  'slack',
+  'discord',
+  'ntfy',
+  'webhook',
+  'telegram',
+  'google-chat',
+  'signal',
+  'whatsapp',
+  'telephony',
+  'imessage',
+  'msteams',
+  'bluebubbles',
+  'mattermost',
+  'matrix',
+  'service',
+];
+
+function readText(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+function isDeliverySurfaceKind(value: string): value is AgentChannelDeliverySurfaceKind {
+  return DELIVERY_SURFACE_KINDS.includes(value as AgentChannelDeliverySurfaceKind);
+}
+
+function parseChannelTarget(raw: string): AgentChannelDeliveryTarget {
+  const [surfaceKind = '', routeId, label] = raw.split(':');
+  if (!isDeliverySurfaceKind(surfaceKind)) {
+    throw new Error(`Unsupported delivery channel "${surfaceKind}".`);
+  }
+  return {
+    kind: 'surface',
+    surfaceKind,
+    ...(readText(routeId) ? { routeId: readText(routeId) } : {}),
+    ...(readText(label) ? { label: readText(label) } : {}),
+  };
+}
+
+function parseRouteTarget(raw: string): AgentChannelDeliveryTarget {
+  const [routeId = '', label] = raw.split(':');
+  const normalizedRouteId = readText(routeId);
+  if (!normalizedRouteId) throw new Error('Route delivery target requires a route id.');
+  return {
+    kind: 'surface',
+    routeId: normalizedRouteId,
+    ...(readText(label) ? { label: readText(label) } : {}),
+  };
+}
+
+function parseWebhookTarget(raw: string): AgentChannelDeliveryTarget {
+  const normalized = readText(raw);
+  if (!normalized) throw new Error('Webhook delivery target requires a URL.');
+  try {
+    const url = new URL(normalized);
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') throw new Error('bad protocol');
+  } catch {
+    throw new Error('Webhook delivery target must be a valid http(s) URL.');
+  }
+  return { kind: 'webhook', address: normalized };
+}
+
+function parseLinkTarget(raw: string): AgentChannelDeliveryTarget {
+  const normalized = readText(raw);
+  if (!normalized) throw new Error('Link delivery target requires a URL or label.');
+  return { kind: 'link', address: normalized };
+}
+
+function selectedTargetInputs(input: AgentChannelDeliveryInput): readonly string[] {
+  return [input.channel, input.route, input.webhook, input.link].map(readText).filter((value): value is string => Boolean(value));
+}
+
+export function buildAgentChannelDeliveryPreview(input: AgentChannelDeliveryInput): AgentChannelDeliveryPreview {
+  const message = readText(input.message);
+  if (!message) throw new Error('Channel delivery message is required.');
+  const targets = selectedTargetInputs(input);
+  if (targets.length === 0) throw new Error('Choose one delivery target: channel, route, webhook, or link.');
+  if (targets.length > 1) throw new Error('Choose exactly one delivery target.');
+
+  const channel = readText(input.channel);
+  const route = readText(input.route);
+  const webhook = readText(input.webhook);
+  const link = readText(input.link);
+  const target = channel
+    ? parseChannelTarget(channel)
+    : route
+      ? parseRouteTarget(route)
+      : webhook
+        ? parseWebhookTarget(webhook)
+        : parseLinkTarget(link ?? '');
+  const title = readText(input.title) ?? 'GoodVibes Agent message';
+  return {
+    message,
+    title,
+    target,
+    request: {
+      target,
+      body: message,
+      title,
+      jobId: 'agent-channel-send',
+      runId: `agent-channel-send-${Date.now()}`,
+      status: 'completed',
+      includeLinks: true,
+      metadata: {
+        product: 'goodvibes-agent',
+        source: 'agent-channel-send',
+      },
+    },
+  };
+}
+
+export async function deliverAgentChannelMessage(
+  router: AgentChannelDeliveryRouter,
+  input: AgentChannelDeliveryInput,
+): Promise<AgentChannelDeliveryResult> {
+  const preview = buildAgentChannelDeliveryPreview(input);
+  const responseId = await router.deliver(preview.request as ChannelDeliveryRequest);
+  return {
+    responseId,
+    message: preview.message,
+    title: preview.title,
+    target: preview.target,
+    strategyCount: router.listStrategies().length,
+  };
+}
+
+function formatTarget(target: AgentChannelDeliveryTarget): string {
+  if (target.kind === 'surface') {
+    const base = target.surfaceKind ?? 'route';
+    const details = [
+      target.routeId ? `route ${target.routeId}` : '',
+      target.label ? `label ${target.label}` : '',
+    ].filter(Boolean);
+    return `${base}${details.length > 0 ? ` (${details.join(', ')})` : ''}`;
+  }
+  return target.address ? `${target.kind} ${target.address}` : target.kind;
+}
+
+export function formatAgentChannelDeliveryPreview(preview: AgentChannelDeliveryPreview, strategyCount: number): string {
+  return [
+    'Agent channel delivery preview',
+    `  title ${preview.title}`,
+    `  target ${formatTarget(preview.target)}`,
+    `  strategies ${strategyCount}`,
+    `  message ${preview.message}`,
+    '  policy external delivery requires an explicit user request and confirmation',
+  ].join('\n');
+}
+
+export function formatAgentChannelDeliveryResult(result: AgentChannelDeliveryResult): string {
+  return [
+    'Agent channel delivery sent',
+    `  title ${result.title}`,
+    `  target ${formatTarget(result.target)}`,
+    `  strategies ${result.strategyCount}`,
+    ...(result.responseId ? [`  response ${result.responseId}`] : []),
+  ].join('\n');
+}