@pellux/goodvibes-tui 2.0.15 → 2.0.16

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to GoodVibes TUI.
 
 ---
 
+## [2.0.16] - 2026-08-21
+
+### Changes
+
+- **The Planning panel drives the real planning command.** The modal invoked
+  `/project-plan`, a command that does not exist; it now runs the registered
+  planning command, and a guard test resolves every command the panels emit
+  against the live command registry so a phantom fails the build.
+- Platform runtime 2.0.20: the pin rides the payments boot-recovery sdk
+  cycle. No TUI code change was needed for it; the reusable-workflow and
+  toolchain pins repoint to the 2.0.20 release commit.
+- Docs verified against the code: install steps match a tested clean
+  install, and term enumerations became code-verified tables.
+
 ## [2.0.15] - 2026-08-21
 
 ### Changes

package/README.md

@@ -6,7 +6,7 @@
 
 GoodVibes is a terminal console for coding and operations work with an AI model. You run `goodvibes` in a project directory and get a full-screen terminal app where you talk to a model that can read and edit your files, run shell commands, search the web, and hand work off to background agents, asking your permission before anything that writes or executes.
 
-It talks to many model providers (OpenAI, Anthropic, Gemini, Bedrock, Copilot, OpenRouter and other OpenAI-compatible gateways, plus local servers like Ollama and LM Studio that it finds on startup), keeps its settings, sessions, and secrets on your own machine, and shows you the token count and running cost of every turn. Alongside the conversation, panels turn background work into live control rooms: running agents, git state, diffs, tokens, cost.
+It talks to many model providers (OpenAI, Anthropic, Gemini, Bedrock, Copilot, OpenRouter and other OpenAI-compatible gateways, plus local servers like Ollama and LM Studio that `/scan` finds on your machine and LAN), keeps its settings, sessions, and secrets on your own machine, and shows you the token count and running cost of every turn. Alongside the conversation, panels turn background work into live control rooms: running agents, git state, diffs, tokens, cost.
 
 <img src="docs/assets/splash.png" alt="GoodVibes starting up in a terminal: a glitch-art GOODVIBES wordmark in cyan-to-magenta gradient, the version and tagline beneath it, the active model and tool count, the working directory, a line offering to resume the last session, and a hint line reading Ctrl+P panels / ? help / F2 fleet. A status footer shows mode, token usage, context usage, and the daemon and web listener addresses." width="900">
 
@@ -25,11 +25,11 @@ Or install from the npm registry with [Bun](https://bun.sh):
 
 ```sh
 bun add -g @pellux/goodvibes-tui
-bun pm trust -g @pellux/goodvibes-tui goodvibes-daemon
+bun pm trust -g @pellux/goodvibes-tui @pellux/goodvibes-daemon
 goodvibes
 ```
 
-Bun blocks lifecycle scripts for untrusted global packages, so the second line lets both postinstalls run: `@pellux/goodvibes-tui`'s own, which places the TUI binary, and `goodvibes-daemon`'s, which places the daemon binary. `goodvibes-daemon` is a real dependency of this package, so one install brings both commands. No other dependency needs trusting. If you skip that step, the `goodvibes` launcher still self-heals on first run by fetching and checksum-verifying its own binary. `npm install -g @pellux/goodvibes-tui` also works when `bun` is already on `PATH`.
+Bun blocks lifecycle scripts for untrusted global packages, so the second line lets both postinstalls run: `@pellux/goodvibes-tui`'s own, which places the TUI binary, and `@pellux/goodvibes-daemon`'s, which places the daemon binary (both names must be the full scoped names). `@pellux/goodvibes-daemon` is a real dependency of this package, so one install brings both commands. No other dependency needs trusting for the install to work. If you skip that step, the `goodvibes` launcher still self-heals on first run by fetching and checksum-verifying its own binary. `npm install -g @pellux/goodvibes-tui` also works when `bun` is already on `PATH`.
 
 Then point it at a model. An environment variable is the fastest path:
 
@@ -57,7 +57,7 @@ The footer keeps an honest running total: fresh input tokens separated from cach
 
 <img src="docs/assets/workspace-trust.png" alt="A modal titled New workspace, choose a trust level, offering two options: Trust this workspace, full capability, all tools may run; and Keep restricted, read-only, explore safely, writes and commands are denied until trusted. Navigation hints read Up/Down Navigate, Enter Choose, Esc Close." width="820">
 
-The first time you open a directory, GoodVibes asks how much it is allowed to do there. Restricted is read-only: the model can look around, but writes and commands are refused until you trust the workspace.
+The first time you open a directory, GoodVibes asks how much it is allowed to do there. Restricted is read-only. The model can look around, but writes and commands are refused until you trust the workspace.
 
 <img src="docs/assets/permission-prompt.png" alt="An execution approval prompt. A header reads EXECUTE, Shell Execution Approval, one more waiting. Fields list the requesting session, the tool exec, the full command mkdir -p build, the working directory, a Risk line reading HIGH write in red, the surface and radius, a summary, the decision class, the effects: process execution, filesystem mutation, possible network access, a reviewer checklist, and the raw tool arguments. Below, four numbered remember options scope an approval to this exact command, to every mkdir command, to every exec call in this project, or to the rest of the session in memory only. The action line reads: Y Allow once, 1-4 Allow and remember, N Deny, or type a reason to deny." width="900">
 
@@ -70,7 +70,7 @@ Four other modes are available when prompting is not what you want:
 - `allow-all` approves everything
 - `custom` takes per-tool `allow` / `prompt` / `deny` overrides
 
-`Shift+Tab` cycles the four session postures: normal, accept-edits, plan, and auto. `/plan` toggles plan mode directly.
+`Shift+Tab` cycles the four session postures: normal (the `prompt` mode), accept-edits, plan, and auto (the `allow-all` mode). `/plan` toggles plan mode directly.
 
 ### Models and providers
 
@@ -109,7 +109,7 @@ Press `?` for a searchable, categorized list of every slash command with its arg
 | `Esc` | Leave the current mode: search, command, or modal |
 | `Ctrl+C` | Clear input, cancel a running turn. Press twice to quit |
 
-Most bindings are customizable in `~/.goodvibes/tui/keybindings.json`, and `/keybindings` shows what is currently bound. Five keys are fixed and stay out of that file: `F2`, `Shift+Tab`, `Esc`, `?`, and `@`. The full reference is in [docs/tools-and-commands.md](docs/tools-and-commands.md).
+Most bindings are customizable in `~/.goodvibes/tui/keybindings.json`, and `/keybindings` shows what is currently bound. Five keys are fixed and stay out of that file: `F2` (Fleet), `Shift+Tab` (permission-mode cycle), `Esc` (leave the current mode), `?` (help), and `@` (file picker). The full reference is in [docs/tools-and-commands.md](docs/tools-and-commands.md).
 
 ---
 
@@ -165,18 +165,27 @@ Edit them live with `/settings` or the fullscreen `/config` workspace rather tha
 | `display.showThinking` | `false` | Show model thinking traces |
 | `behavior.autoCompactThreshold` | `80` | Context percentage before auto-compact runs |
 | `helper.enabled` | `false` | Route grunt work to a cheaper helper model |
-| `daemon.enabled` | `true` | Spawn or adopt a detached local session daemon, bound to loopback |
+| `daemon.enabled` | `true` | Adopt a local session daemon on loopback; off makes no adoption attempt |
 
 The wider key table, the permission modes, and the hand-edited TUI namespaces (checkpoint root guard, scriptable statusline, session behavior, launch-time self-update) are in [docs/configuration.md](docs/configuration.md).
 
 ### Where things are stored
 
-- global settings `~/.goodvibes/tui/settings.json`, project settings `.goodvibes/tui/settings.json`
-- encrypted secrets `~/.goodvibes/tui/secrets.enc` or `.goodvibes/tui/secrets.enc`
-- custom providers `~/.goodvibes/tui/providers/*.json`, keybindings `~/.goodvibes/tui/keybindings.json`
-- service registry `.goodvibes/tui/services.json`, schedules `.goodvibes/tui/schedules.json`
-- agent archetypes `.goodvibes/agents/*.md`, MCP servers `.goodvibes/mcp.json`, hooks `.goodvibes/hooks.json`
-- sessions, artifacts, and other project runtime state under `.goodvibes/` in the working directory
+Everything lives in plain files, split between the per-user `~/.goodvibes/tui/` tree and the project's own `.goodvibes/` directory:
+
+| Path | What lives there |
+| --- | --- |
+| `~/.goodvibes/tui/settings.json` | Global settings |
+| `.goodvibes/tui/settings.json` | Project settings overriding the global layer |
+| `~/.goodvibes/tui/secrets.enc` or `.goodvibes/tui/secrets.enc` | Encrypted secrets, global or per project |
+| `~/.goodvibes/tui/providers/*.json` | Custom provider definitions, hot-reloaded |
+| `~/.goodvibes/tui/keybindings.json` | Keybinding overrides |
+| `.goodvibes/tui/services.json` | The service registry |
+| `.goodvibes/tui/automation-*.json` | Scheduled jobs and the rest of the automation store |
+| `.goodvibes/agents/*.md` | Agent archetypes |
+| `.goodvibes/mcp.json` | MCP server definitions |
+| `.goodvibes/hooks.json` | Hooks and hook chains |
+| `.goodvibes/` (rest) | Sessions, artifacts, and other project runtime state in the working directory |
 
 ---
 
@@ -204,10 +213,10 @@ bun run dev
 | Command | Does |
 | --- | --- |
 | `bun run dev` | Run the TUI from source |
-| `bun test` | Run the suite through the parallel per-file runner |
+| `bun run test` | Run the suite through the parallel per-file runner |
 | `bun run build` | Compile `src/main.ts` into `dist/goodvibes` |
 
-The compiled binary is the TUI entrypoint. It adopts a running standalone GoodVibes daemon, or starts one already installed as a stopped service, and hosts the HTTP listener when `danger.httpListener` is enabled. It never spawns a new daemon process itself (`daemon.enabled`, on by default, loopback-bound).
+The compiled binary is the TUI entrypoint. With `daemon.enabled` on (the default) it adopts a running standalone GoodVibes daemon over loopback, and when a daemon is installed as a service but stopped, it starts that service once and waits for it to come online. It never embeds or constructs a daemon of its own. The control plane, HTTP listener (`danger.httpListener`), and web surface are all hosted by the daemon; the TUI configures them and reports their bindings.
 
 Tests live under `src/test/`, mirroring the source tree, and cover contract, security, release-gate, runtime, renderer, panel, integration, and anti-regression cases. Several gates run alongside them in CI: byte-exact golden renderer frames, performance budgets for startup and frame composition and line production (`scripts/perf-baseline.json`), and architecture rules for import cycles, layer boundaries, source-file size, and unused renderer exports (`scripts/check-architecture.ts`).
 
@@ -237,10 +246,10 @@ src/
 ├── config/                 settings layering, surface roots, secrets, credential availability
 ├── permissions/            approval cards, hunk selection, sandbox exec gate
 ├── cli/                    flag parsing, management verbs, doctor, launch-time self-update
-├── tools/, mcp/, plugins/  TUI-local tool guards, MCP hot reload, plugin loader
-├── audio/, export/         turn playback and speech routing, cost pricing and gist upload
-├── verification/, work-plans/, widget/    live verifier and ledger, work-plan store, widget module
-├── utils/, types/, scripts/               formatting and clipboard helpers, local types, message script
+├── tools/, mcp/            TUI-local tool guards, MCP runtime reload
+├── audio/, export/         voice capture, wake word, playback and speech routing; gist upload
+├── verification/, widget/  live verifier and its ledger, the terminal widget module
+├── utils/, scripts/        formatting and clipboard helpers, message processing script
 └── test/                   the suite, mirroring the tree above
 ```
 

package/docs/README.md

@@ -8,13 +8,13 @@ This directory contains the current product documentation for `goodvibes-tui`.
   Installation, first-run setup, provider configuration, common paths, and basic run/build flows.
 
 - [Configuration reference](configuration.md)
-  The layered settings model, the key-settings table, permission modes and the policy/trust system, plus the TUI-owned namespaces you add by hand to settings.json: checkpoint root guard, the scriptable statusline, session behavior, and launch-time self-update.
+  The layered settings model, a curated key-settings table, permission modes and the policy/trust system, plus the TUI-owned namespaces you add by hand to settings.json, covering the checkpoint root guard, the scriptable statusline, session behavior, notification alert classes, and launch-time self-update.
 
 - [Deployment and services](deployment-and-services.md)
   TUI-only mode, compiled binary behavior, adopting or autostarting the daemon, the in-process HTTP listener, inbound TLS, outbound trust configuration, control-plane entrypoints, the service registry and secret references, profiles and setup transfer, and integration helpers.
 
 - [Remote access: a home server setup](remote-access.md)
-  Step-by-step continuity setup: daemon on an always-on box, webui from any browser, TUI over SSH, Tailscale for reachability and TLS, validated by `goodvibes doctor`.
+  Step-by-step continuity setup covering the daemon on an always-on box, webui from any browser, TUI over SSH, Tailscale for reachability and TLS, and validation with `goodvibes doctor`.
 
 - [Providers and routing](providers-and-routing.md)
   Native providers, compatible/gateway providers, local discovery, synthetic failover, search providers, voice providers, and media providers.
@@ -38,13 +38,13 @@ This directory contains the current product documentation for `goodvibes-tui`.
   Omnichannel surfaces, reply routing, remote peers, node-host contracts, and the daemon/control-plane HTTP + streaming surfaces.
 
 - [Session durability](session-durability.md)
-  Two-layer durability: post-turn snapshots plus periodic recovery files, and the fsync-per-record transcript journal replayed at every resume seam.
+  Two-layer durability, combining post-turn snapshots plus periodic recovery files with the fsync-per-record transcript journal replayed at every resume seam.
 
 - [Share command](share-command.md)
   `/share` session export to HTML/JSON/Markdown with redaction, upload, clipboard, and open options.
 
 - [CLI flags](cli-flags.md)
-  Global flags reference: session lifecycle (`--continue`, `--resume`, `--fork`), confirmation bypass (`-y`/`--non-interactive`), output format consolidation, `--host` alias, and all other startup and command-specific flags.
+  Global flags reference covering session lifecycle (`--continue`, `--resume`, `--fork`), the `-y`/`--non-interactive` commit gate for plugin bundle installs, output format consolidation, the `--host` alias, and all other startup and command-specific flags.
 
 - [Commands reference](commands-reference.md)
   The generated, categorized list of every slash command, its arguments, and its description. It is the same list `?` renders in the product.
@@ -74,4 +74,4 @@ This directory contains the current product documentation for `goodvibes-tui`.
   Checked-in operator and peer contract manifests plus canonical knowledge GraphQL and SQL artifacts for release-gate and SDK extraction work.
 
 - [GitHub Action](github-action.md)
-  The `run-goodvibes` composite action: installing a pinned, checksum-verified release in CI and running a non-interactive command or prompt against a workspace.
+  The `run-goodvibes` composite action, which installs a pinned, checksum-verified release in CI and runs a non-interactive command or prompt against a workspace.

package/docs/foundation-artifacts/operator-contract.json

@@ -3,7 +3,7 @@
   "product": {
     "id": "goodvibes",
     "surface": "operator",
-    "version": "2.0.19"
+    "version": "2.0.20"
   },
   "auth": {
     "modes": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-tui",
-  "version": "2.0.15",
+  "version": "2.0.16",
   "description": "Terminal-native GoodVibes client for coding, operations, knowledge and channel workflows; a pure client of the GoodVibes daemon.",
   "type": "module",
   "main": "src/main.ts",
@@ -96,8 +96,8 @@
     "@anthropic-ai/bedrock-sdk": "^0.29.1",
     "@anthropic-ai/sdk": "^0.92.0",
     "@ast-grep/napi": "^0.42.0",
-    "@pellux/goodvibes-sdk": "2.0.19",
-    "@pellux/goodvibes-terminal-shell": "2.0.19",
+    "@pellux/goodvibes-sdk": "2.0.20",
+    "@pellux/goodvibes-terminal-shell": "2.0.20",
     "bash-language-server": "^5.6.0",
     "fuse.js": "^7.1.0",
     "@pellux/goodvibes-daemon": "1.28.21",
@@ -121,7 +121,7 @@
     "zustand": "^5.0.12"
   },
   "devDependencies": {
-    "@pellux/goodvibes-toolchain": "2.0.19",
+    "@pellux/goodvibes-toolchain": "2.0.20",
     "@types/bun": "^1.3.10",
     "typescript": "^5.9.3"
   },

package/src/input/commands/planning-runtime.ts

@@ -9,7 +9,7 @@ import { openModalCommand, requirePlanManager, requireSessionLineageTracker } fr
 import { togglePlanMode, permissionModeLabel, type PermissionModeValue } from '../../core/permission-mode.ts';
 
 /**
- * Single-token verbs that look like a `/plan` subcommand but are not real ones.
+ * Single-token verbs that look like a `/project-plan` subcommand but are not real ones.
  * A lone one of these is refused rather than seeded as a goal, so a stray verb
  * can never overwrite the project goal with itself.
  *
@@ -165,7 +165,7 @@ export function registerPlanningRuntimeCommands(registry: CommandRegistry): void
       if (args[0] === 'show') {
         const id = args[1];
         if (!id) {
-          ctx.print('Usage: /plan show <plan-id>');
+          ctx.print('Usage: /project-plan show <plan-id>');
           return;
         }
         const plans = planManager.list();
@@ -178,16 +178,16 @@ export function registerPlanningRuntimeCommands(registry: CommandRegistry): void
         return;
       }
 
-      // /plan dismiss, archive the current plan. Dismisses the active
+      // /project-plan dismiss, archive the current plan. Dismisses the active
       // execution plan (ExecutionPlanManager.dismiss, honest per-state) AND
       // deactivates the project-planning interview state shown in the modal so a
-      // later /plan <goal> starts fresh. Mid-execution is refused outright.
+      // later /project-plan <goal> starts fresh. Mid-execution is refused outright.
       if (args[0] === 'dismiss') {
         const dismissal = planManager.dismiss(ctx.session.runtime.sessionId);
         if (dismissal.outcome === 'requires-cancel') {
           ctx.print(
             `Plan "${dismissal.blockedBy?.title ?? 'active plan'}" is mid-execution and was not dismissed. ` +
-            `Run /workstream cancel to stop it first, then /plan dismiss.`,
+            `Run /workstream cancel to stop it first, then /project-plan dismiss.`,
           );
           return;
         }
@@ -213,7 +213,7 @@ export function registerPlanningRuntimeCommands(registry: CommandRegistry): void
         if (dismissal.outcome === 'dismissed') {
           ctx.print(
             `Dismissed plan "${dismissal.plan?.title ?? 'active plan'}" ` +
-            `(archived as dismissed; retained in /plan list; /plan <goal> starts fresh).${planningNote}`,
+            `(archived as dismissed; retained in /project-plan list; /project-plan <goal> starts fresh).${planningNote}`,
           );
         } else if (planningNote) {
           ctx.print(`No active execution plan to dismiss.${planningNote}`);
@@ -223,7 +223,7 @@ export function registerPlanningRuntimeCommands(registry: CommandRegistry): void
         return;
       }
 
-      // /plan answer <n|question-id> <text>, record a real answer to an
+      // /project-plan answer <n|question-id> <text>, record a real answer to an
       // open planning question (moves open → answered, consumed on next refine).
       if (args[0] === 'answer') {
         if (!projectPlanningService || !projectId) {
@@ -233,7 +233,7 @@ export function registerPlanningRuntimeCommands(registry: CommandRegistry): void
         const ref = args[1];
         const answerText = args.slice(2).join(' ').trim();
         if (!ref || !answerText) {
-          ctx.print('Usage: /plan answer <question-number|question-id> <your answer>');
+          ctx.print('Usage: /project-plan answer <question-number|question-id> <your answer>');
           return;
         }
         const asNum = Number(ref);
@@ -243,7 +243,7 @@ export function registerPlanningRuntimeCommands(registry: CommandRegistry): void
         const answerResult = await projectPlanningService.answerQuestion({ projectId, ...selector, answer: answerText });
         if (!answerResult.answered) {
           if (answerResult.reason === 'no-state') {
-            ctx.print('No project planning state exists yet. Seed it with /plan <goal>.');
+            ctx.print('No project planning state exists yet. Seed it with /project-plan <goal>.');
           } else if (answerResult.reason === 'question-not-found') {
             const open = answerResult.openQuestions;
             const listing = open.length > 0
@@ -251,7 +251,7 @@ export function registerPlanningRuntimeCommands(registry: CommandRegistry): void
               : '  (no open questions)';
             ctx.print(`No open question matched "${ref}". Open questions:\n${listing}`);
           } else {
-            ctx.print('Usage: /plan answer <question-number|question-id> <your answer>');
+            ctx.print('Usage: /project-plan answer <question-number|question-id> <your answer>');
           }
           return;
         }
@@ -273,8 +273,8 @@ export function registerPlanningRuntimeCommands(registry: CommandRegistry): void
       // corrupting the goal.
       if (args.length === 1 && PSEUDO_SUBCOMMAND_VERBS.has(args[0].toLowerCase())) {
         ctx.print(
-          `Unknown /plan subcommand "${args[0]}": did you mean panel, approve, list, show, or status? ` +
-          `To seed a planning goal, use /plan <a real sentence describing the change>.`,
+          `Unknown /project-plan subcommand "${args[0]}": did you mean panel, approve, list, show, or status? ` +
+          `To seed a planning goal, use /project-plan <a real sentence describing the change>.`,
         );
         return;
       }
@@ -289,7 +289,7 @@ export function registerPlanningRuntimeCommands(registry: CommandRegistry): void
         state: {
           goal: taskDescription,
           knownContext: [
-            `Workspace planning was seeded from the TUI /plan command.`,
+            `Workspace planning was seeded from the TUI /project-plan command.`,
           ],
           metadata: {
             active: true,

package/src/panels/modals/planning-modal.ts

@@ -219,11 +219,11 @@ class PlanningModalSurface implements ConfigModalSurface {
 
   onAction(id: string, ctx: ConfigModalActionContext): void {
     if (id === 'refresh') { this.refresh(); ctx.setStatus('Reloading project planning state…'); return; }
-    if (id === 'approve') { void ctx.executeCommand?.('plan', ['approve']); ctx.setStatus('Dispatched /plan approve.'); return; }
+    if (id === 'approve') { void ctx.executeCommand?.('project-plan', ['approve']); ctx.setStatus('Dispatched /project-plan approve.'); return; }
     if (id === 'dismiss') {
       // First-class, confirmed (host two-press) mutating dismiss.
-      void ctx.executeCommand?.('plan', ['dismiss']);
-      ctx.setStatus('Dispatched /plan dismiss.');
+      void ctx.executeCommand?.('project-plan', ['dismiss']);
+      ctx.setStatus('Dispatched /project-plan dismiss.');
       ctx.close();
       return;
     }
@@ -232,18 +232,18 @@ class PlanningModalSurface implements ConfigModalSurface {
     if (!question || actions.length === 0) return;
     const action = ctx.row ? actions.find((a) => a.id === ctx.row!.id) : undefined;
     if (!action || action.disabled) { ctx.print('Choose an answer option.'); return; }
-    if (action.kind === 'approve') { void ctx.executeCommand?.('plan', ['approve']); ctx.setStatus('Dispatched /plan approve.'); return; }
+    if (action.kind === 'approve') { void ctx.executeCommand?.('project-plan', ['approve']); ctx.setStatus('Dispatched /project-plan approve.'); return; }
 
     const answerText = action.answer.trim();
     if (!answerText) { ctx.print('Choose a non-empty answer, or type an answer for the custom row.'); return; }
 
-    // A canned answer to a REAL open question records structurally via /plan answer.
+    // A canned answer to a REAL open question records structurally via /project-plan answer.
     const isOpenQuestion = this.snapshot?.state?.openQuestions.some(
       (q) => q.id === question.id && (q.status ?? 'open') === 'open',
     ) ?? false;
     if (action.id !== 'custom' && isOpenQuestion) {
-      void ctx.executeCommand?.('plan', ['answer', question.id, ...answerText.split(/\s+/)]);
-      ctx.setStatus('Dispatched /plan answer for the current question.');
+      void ctx.executeCommand?.('project-plan', ['answer', question.id, ...answerText.split(/\s+/)]);
+      ctx.setStatus('Dispatched /project-plan answer for the current question.');
       return;
     }