@pellux/goodvibes-tui 2.0.14 → 2.0.16

package/.goodvibes/GOODVIBES.md

@@ -1,7 +1,7 @@
 ## MANDATORY
 
 PRIMARY GOAL: Fully complete and functional code that meets or exceeds the minimum review score
-SECONDARY GOAL: Minimize token usage — use the minimum data necessary to complete each task
+SECONDARY GOAL: Minimize token usage. Use the minimum data necessary to complete each task
 
 GENERAL DIRECTIVES: 
  - Every plan must have a multi-agent execution strategy.

package/.goodvibes/agents/reviewer.md

@@ -6,7 +6,7 @@ tools: [read, find, analyze]
 
 You are a code reviewer for the WRFC (Work-Review-Fix-Complete) chain. Your job is to assess agent work against a rigorous 10-dimension rubric. You verify claims by reading actual files. You never trust self-reported results blindly.
 
-## 10-Dimension Scoring Rubric
+## 10-dimension scoring rubric
 
 Each dimension is scored 0.0 to 1.0. Maximum total score is 10.0.
 
@@ -23,7 +23,7 @@ Each dimension is scored 0.0 to 1.0. Maximum total score is 10.0.
 | Completeness | 1.0 | All requirements met, no TODOs left, no partial implementations, no placeholders? |
 | Integration | 1.0 | Fits with existing architecture, no circular deps, proper imports, backward compatible? |
 
-## Scoring Rules
+## Scoring rules
 
 - Each dimension scored 0.0 to 1.0 in 0.05 increments
 - Every deduction MUST cite a specific issue with file path, line number (if applicable), and severity
@@ -36,16 +36,16 @@ Each dimension is scored 0.0 to 1.0. Maximum total score is 10.0.
 - Goal is always 10.0. The threshold is the MINIMUM acceptable score.
 - Only score dimensions relevant to the task scope. If a phase explicitly excludes testing (e.g., type-only changes), score Testing as 1.0 with a note that it's N/A for this scope.
 
-## Review Process
+## Review process
 
 1. Read the agent's completion report (provided in the task)
-2. Read EVERY file mentioned in the report — verify claims against actual code
+2. Read EVERY file mentioned in the report. Verify claims against actual code
 3. Check for files that should have been changed but weren't
 4. Score each dimension independently
 5. List all issues with severity, description, file, line, and point value
 6. Produce a ReviewerReport JSON block
 
-## Output Format
+## Output format
 
 You MUST end your response with a structured ReviewerReport JSON block. You MUST wrap the ReviewerReport in triple-backtick json fences (```json ... ```) for reliable parsing.
 
@@ -75,15 +75,15 @@ You MUST end your response with a structured ReviewerReport JSON block. You MUST
 }
 ```
 
-## Anti-Patterns to Avoid
+## Anti-patterns to avoid
 
 - Never give a perfect 10.0 unless the code is genuinely flawless
 - Never pass code that has placeholder implementations ("TODO", "not implemented")
 - Never trust file lists in the report without verifying they exist and contain what's claimed
 - If you can't read a file (permission error, doesn't exist), that's an automatic deduction
 
-## What You Will NOT Do
+## What you will NOT do
 
 - You do NOT run tests (quality gates handle that separately)
 - You do NOT modify any code
-- You do NOT write implementation code or provide code fixes — only identify issues. Suggestions may propose alternative design approaches but never include code.
+- You do NOT write implementation code or provide code fixes. Only identify issues. Suggestions may propose alternative design approaches but never include code.

package/.goodvibes/skills/add-provider/SKILL.md

@@ -13,13 +13,13 @@ triggers:
 author: goodvibes
 ---
 
-# Add Custom Provider
+# Add custom provider
 
 Interactively collect provider and model details from the user, then write a JSON config to `~/.goodvibes/tui/providers/{name}.json`.
 
 ## Workflow
 
-### Step 1: Check for Existing Provider
+### Step 1: Check for existing provider
 
 Before collecting info, check if `~/.goodvibes/tui/providers/` already has JSON files. If the user names a provider that already exists, ask:
 - **Add models** to the existing provider, or
@@ -27,22 +27,22 @@ Before collecting info, check if `~/.goodvibes/tui/providers/` already has JSON
 
 If adding models, read the existing JSON, append new models, and write back.
 
-### Step 2: Collect Provider Details
+### Step 2: Collect provider details
 
 Ask the user for each field. Apply smart defaults when the provider name matches a known service.
 
-#### Required Fields
+#### Required fields
 
 | Field | Description | Validation |
 |-------|-------------|------------|
 | `name` | Internal ID | Lowercase alphanumeric + hyphens only, 1-64 chars |
 | `displayName` | Human-readable name | Non-empty string |
-| `type` | API compatibility | `openai-compat` (recommended) or `anthropic-compat` (not yet supported — use `openai-compat`) |
+| `type` | API compatibility | `openai-compat` (recommended) or `anthropic-compat` (not yet supported, use `openai-compat`) |
 | `baseURL` | API endpoint | Must start with `http://` or `https://` |
 
-> **Note:** `anthropic-compat` is accepted in the JSON schema for forward compatibility but is not yet functional at runtime. The loader will skip configs with this type and emit a warning. Use `openai-compat` for now — most Anthropic-compatible proxies (e.g., via LiteLLM) expose an OpenAI-compatible endpoint.
+> **Note:** `anthropic-compat` is accepted in the JSON schema for forward compatibility but is not yet functional at runtime. The loader will skip configs with this type and emit a warning. Use `openai-compat` for now. Most Anthropic-compatible proxies (e.g., via LiteLLM) expose an OpenAI-compatible endpoint.
 
-#### Optional Fields
+#### Optional fields
 
 | Field | Description | Default |
 |-------|-------------|---------|
@@ -50,7 +50,7 @@ Ask the user for each field. Apply smart defaults when the provider name matches
 | `apiKey` | Explicit API key (not recommended) | None |
 | `defaultHeaders` | Custom HTTP headers sent with every API request (e.g., for proxy authentication or routing) | None |
 
-### Smart Defaults
+### Smart defaults
 
 When the user mentions a known provider, pre-fill these values and confirm:
 
@@ -100,7 +100,7 @@ vllm:
 
 If the name does not match a known provider, ask for all fields individually.
 
-### Step 3: Collect Model Details
+### Step 3: Collect model details
 
 Collect at least one model. For each model:
 
@@ -118,7 +118,7 @@ Collect at least one model. For each model:
 
 After each model, ask: "Add another model?" Loop until done.
 
-### Step 4: Preview and Confirm
+### Step 4: Preview and confirm
 
 Show the complete JSON to the user and ask for confirmation before writing.
 
@@ -148,13 +148,13 @@ Example output:
 }
 ```
 
-### Step 5: Write the File
+### Step 5: Write the file
 
 Write to `~/.goodvibes/tui/providers/{name}.json`. Create the directory if it does not exist.
 
 Use `precision_write` with `mode: "fail_if_exists"` for new providers. Use `mode: "overwrite"` when the user chose to overwrite an existing provider or when merging models into an existing file.
 
-If the `apiKeyEnv` field is set, include it in the JSON. If the user provided an explicit `apiKey`, include it but warn that storing keys in plain text is not recommended -- suggest using an environment variable instead.
+If the `apiKeyEnv` field is set, include it in the JSON. If the user provided an explicit `apiKey`, include it but warn that storing keys in plain text is not recommended. Suggest using an environment variable instead.
 
 If `defaultHeaders` were provided, include them.
 
@@ -165,7 +165,7 @@ Tell the user:
 - The provider should be available immediately if goodvibes-tui is currently running (it hot-reloads custom provider configs); if not running, changes take effect on next startup
 - If an API key is needed, remind them to set the environment variable
 
-## Validation Rules
+## Validation rules
 
 Before writing, verify:
 1. `name` matches `/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/` and is 1-64 characters (no trailing hyphens)
@@ -176,24 +176,24 @@ Before writing, verify:
 
 If validation fails, tell the user which field is invalid and ask for correction.
 
-## JSON Schema Reference
+## JSON schema reference
 
 The provider JSON maps to the codebase types:
 
-- Provider registration uses `OpenAICompatProvider` for `openai-compat` type. The `anthropic-compat` type is parsed and accepted in the JSON but is **not yet supported at runtime** — the loader skips it with a warning. Recommend `openai-compat` for all custom providers.
+- Provider registration uses `OpenAICompatProvider` for `openai-compat` type. The `anthropic-compat` type is parsed and accepted in the JSON but is **not yet supported at runtime**. The loader skips it with a warning. Recommend `openai-compat` for all custom providers.
 - `OpenAICompatOptions`: `{ name, baseURL, apiKey, defaultModel, models }`
 - Model entries map to `ModelDefinition`: `{ id, provider, displayName, description, contextWindow, capabilities, reasoningEffort?, selectable }`
-  - `reasoningEffort?: string[]` — optional array of supported effort levels, e.g., `["low", "medium", "high"]`
+  - `reasoningEffort?: string[]` is an optional array of supported effort levels, e.g., `["low", "medium", "high"]`
 - The `selectable` field defaults to `true` for custom models
 - The `provider` field in `ModelDefinition` is auto-set to the provider `name`
 
-## Conversational Style
+## Conversational style
 
 Be natural and helpful. Guide users step-by-step but do not be overly verbose. If the user provides multiple details at once (e.g., "add ollama with llama3.3-70b"), extract what you can and only ask for missing fields.
 
-## Edge Cases
+## Edge cases
 
-- **Unknown context window**: Suggest 4096 as a safe default, note the user can update later
-- **No API key needed**: Omit `apiKeyEnv` and `apiKey` from the JSON entirely
-- **User provides a full JSON blob**: Validate it against the schema and write directly
-- **Multiple providers in one session**: After completing one, ask if they want to add another
+- **Unknown context window.** Suggest 4096 as a safe default, and note the user can update later.
+- **No API key needed.** Omit `apiKeyEnv` and `apiKey` from the JSON entirely.
+- **User provides a full JSON blob.** Validate it against the schema and write directly.
+- **Multiple providers in one session.** After completing one, ask if they want to add another.

package/CHANGELOG.md

@@ -4,6 +4,55 @@ 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
+
+- **Wake-word WASM assets are written by the SDK's own atomic writer**
+  (platform runtime 2.0.19): `atomicWriteFileSync` now accepts raw bytes,
+  not just strings, so the onnxruntime glue and WASM files this terminal
+  extracts to disk go through the same temp-file-then-rename-and-fsync path
+  as every other file this client writes, instead of a hand-rolled copy
+  inlined in the wake module. Same content check, same target names, same
+  crash-safety guarantee, one less code path to keep correct.
+- **Release publishing is gated before a tag exists, not after.** The
+  sdk-pin check now runs in CI on every push instead of only after a
+  GitHub Release was already cut, the GitHub Packages mirror publish is
+  ordered behind the npmjs publish and carries the same kill switch, and
+  the release workflow verifies the git tag matches the package version as
+  its first job. CI now builds through the real toolchain and runs the
+  compiled binary's smoke test on pull requests too, not just a bare
+  compile. The four sdk reusable-workflow references are pinned to a
+  commit sha instead of floating on the sdk's default branch, so a commit
+  to the sdk repository can no longer change what runs against this
+  repository's publish credentials without a deliberate pin bump here.
+- Comment and documentation prose across the source tree had its em dashes
+  removed and its narration comments trimmed; a handful of command
+  descriptions changed wording to match, so the regenerated command
+  reference and eighteen golden UI frames moved with them. No command
+  behavior changed.
+- Bundled platform runtime moves to 2.0.19, the checkout-seam/wake-fix
+  cycle. Execution plans this terminal writes round-trip through their own
+  markdown again now that the emitter and parser agree on a separator.
+- Bundled daemon moves to 1.28.21, which serves the repaired
+  `voice.wake.model.get` verb. That fix reaches this surface directly: the
+  wake feature fetches its models from that same verb, and the request
+  failed against every daemon build before this pin.
+
 ## [2.0.14] - 2026-08-15
 
 ### Changes

package/README.md

@@ -2,9 +2,11 @@
 
 [![CI](https://github.com/mgd34msu/goodvibes-tui/actions/workflows/ci.yml/badge.svg)](https://github.com/mgd34msu/goodvibes-tui/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Version](https://img.shields.io/badge/version-2.0.14-blue.svg)](https://github.com/mgd34msu/goodvibes-tui)
+[![Version](https://img.shields.io/badge/version-2.0.15-blue.svg)](https://github.com/mgd34msu/goodvibes-tui)
 
-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 — running agents, git state, diffs, tokens, cost — into live control rooms.
+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 `/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">
 
@@ -23,21 +25,21 @@ 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 — a real dependency of this package, so one install brings both commands — which places the daemon binary. 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:
+Then point it at a model. An environment variable is the fastest path:
 
 ```sh
 export OPENAI_API_KEY=...
 ```
 
-On Windows, run it inside a WSL2 distribution, where it is an ordinary Linux install. Native Windows is beta — see [docs/windows.md](docs/windows.md).
+On Windows, run it inside a WSL2 distribution, where it is an ordinary Linux install. Native Windows is beta. See [docs/windows.md](docs/windows.md).
 
-Deeper install notes — the installer's environment variables, uninstall, daemon service registration, encrypted and vault-backed secrets, and running from source — are in [docs/getting-started.md](docs/getting-started.md).
+Deeper install notes are in [docs/getting-started.md](docs/getting-started.md): the installer's environment variables, uninstall, daemon service registration, encrypted and vault-backed secrets, and running from source.
 
 ---
 
@@ -47,7 +49,7 @@ Deeper install notes — the installer's environment variables, uninstall, daemo
 
 <img src="docs/assets/conversation.png" alt="Two conversation turns in the terminal. The tail of an earlier answer describes the project as a minimal ISS pass tracker whose calculation is still a stub. Below it the user asks the model to grep for nextPass and list every file that references it; an assistant block shows one find tool call with a green checkmark, and its result is expanded as syntax-highlighted JSON with line numbers listing the two matching file paths and a count of 2. The final answer names src/passes.ts and src/index.ts as a bulleted list. The footer reads Token Usage: Input em dash, Output 264, Cache Read 0, Cache Write 0, Total 264, approximately 0.0040 dollars, above a green context usage bar at 4 percent." width="900">
 
-Tool calls stream inline as the model makes them, then their results fold into a collapsible group so a long working session stays readable — expand any group to see what actually came back. Assistant messages render markdown, syntax-highlighted code, and inline diffs, and any block can be collapsed, bookmarked, copied, or saved to a file.
+Tool calls stream inline as the model makes them, then their results fold into a collapsible group so a long working session stays readable. Expand any group to see what actually came back. Assistant messages render markdown, syntax-highlighted code, and inline diffs, and any block can be collapsed, bookmarked, copied, or saved to a file.
 
 The footer keeps an honest running total: fresh input tokens separated from cache reads, output tokens, the estimated cost so far, and how much of the context window is used. When a model's price is not in the catalog, the cost is reported as unavailable rather than guessed.
 
@@ -55,11 +57,20 @@ 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">
 
-After that, the default permission mode is `prompt`: writes, edits, shell commands, network fetches, agent spawns, and MCP calls each stop and ask. The prompt shows what will run, in which directory, its assessed risk, and what it can affect. You can allow it once, deny it (optionally typing a reason the model sees), or remember the decision at whichever scope fits — this exact command, this command shape, this tool for the whole project, or just for the rest of the session. Four other modes are available when prompting is not what you want: `accept-edits` auto-approves file writes and edits while exec and the other risky classes still ask, `plan` allows read-only tools and refuses every mutating or exec call, `allow-all` approves everything, and `custom` takes per-tool `allow` / `prompt` / `deny` overrides. `Shift+Tab` cycles the four session postures — normal, accept-edits, plan, auto — and `/plan` toggles plan mode directly.
+After that, the default permission mode is `prompt`: writes, edits, shell commands, network fetches, agent spawns, and MCP calls each stop and ask. The prompt shows what will run, in which directory, its assessed risk, and what it can affect. You can allow it once, deny it (optionally typing a reason the model sees), or remember the decision at whichever scope fits: this exact command, this command shape, this tool for the whole project, or just for the rest of the session.
+
+Four other modes are available when prompting is not what you want:
+
+- `accept-edits` auto-approves file writes and edits while exec and the other risky classes still ask
+- `plan` allows read-only tools and refuses every mutating or exec call
+- `allow-all` approves everything
+- `custom` takes per-tool `allow` / `prompt` / `deny` overrides
+
+`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
 
@@ -67,13 +78,13 @@ After that, the default permission mode is `prompt`: writes, edits, shell comman
 
 Models come from a live catalog, so the picker lists far more than a hardcoded set, filterable by search, price, capability, and availability. Separate roles route independently: your main chat model, a cheaper helper model for grunt work, a tool model, a TTS model, and an embeddings model can each point somewhere different.
 
-The `synthetic` provider groups the same model across every backend that serves it into one entry. Pick it and requests route to whichever backend is healthy, failing over on rate limits and transient errors without changing the model you chose — and without ever crossing the free, paid, and subscription boundaries. Any OpenAI-compatible API can be added as a custom provider by dropping a JSON file in `~/.goodvibes/tui/providers/`; it is hot-reloaded. See [docs/providers-and-routing.md](docs/providers-and-routing.md).
+The `synthetic` provider groups the same model across every backend that serves it into one entry. Pick it and requests route to whichever backend is healthy, failing over on rate limits and transient errors without changing the model you chose, and without ever crossing the free, paid, and subscription boundaries. Any OpenAI-compatible API can be added as a custom provider by dropping a JSON file in `~/.goodvibes/tui/providers/`. It is hot-reloaded. See [docs/providers-and-routing.md](docs/providers-and-routing.md).
 
 ### The Fleet control room
 
-<img src="docs/assets/fleet-panel.png" alt="The Fleet panel open beside the conversation. It lists background work as rows with a kind, a name, elapsed time, token count, and cost — a CI watch poller and a runtime heartbeat watcher at 4 minutes 23 seconds each, and an idle code indexer. The detail region below shows the selected watcher's id, state idle, elapsed time, model, tokens, cost, a headline reading CI watch poller, healthy, an activity phase, and an approvals line. The action hints read j/k navigate, Enter attach, K kill, A archive finished, v archived, n host agent." width="900">
+<img src="docs/assets/fleet-panel.png" alt="The Fleet panel open beside the conversation. It lists background work as rows with a kind, a name, elapsed time, token count, and cost: a CI watch poller and a runtime heartbeat watcher at 4 minutes 23 seconds each, and an idle code indexer. The detail region below shows the selected watcher's id, state idle, elapsed time, model, tokens, cost, a headline reading CI watch poller, healthy, an activity phase, and an approvals line. The action hints read j/k navigate, Enter attach, K kill, A archive finished, v archived, n host agent." width="900">
 
-Work that is not conversation goes into panels instead of scrolling past in the transcript. Fleet — reached with `F2` — is the live control room for agents, workstreams, watchers, and scheduled jobs: what is running, for how long, at what token cost, and what it is waiting on. You can attach to a running agent to watch or steer it, detach again without killing it, pause and resume, and archive finished work. Git, diff, cost, token, and local-auth panels sit alongside it; heavier operator surfaces open as review modals.
+Work that is not conversation goes into panels instead of scrolling past in the transcript. Fleet, reached with `F2`, is the live control room for agents, workstreams, watchers, and scheduled jobs: what is running, for how long, at what token cost, and what it is waiting on. You can attach to a running agent to watch or steer it, detach again without killing it, pause and resume, and archive finished work. Git, diff, cost, token, and local-auth panels sit alongside it. Heavier operator surfaces open as review modals.
 
 ### Everything else is a command
 
@@ -87,18 +98,18 @@ Press `?` for a searchable, categorized list of every slash command with its arg
 | --- | --- |
 | `Enter` / `Shift+Enter` | Send the message / insert a newline |
 | `?` | Help and command picker (on an empty prompt) |
-| `@` | File picker — insert a path into the prompt |
+| `@` | File picker: insert a path into the prompt |
 | `Tab` | Toggle collapse on the nearest block, or complete a path |
 | `Ctrl+F` | Search the conversation |
 | `Ctrl+Y` / `Ctrl+S` | Copy / save the nearest block |
 | `Ctrl+P` | Toggle the panel sidebar |
-| `F2` | Toggle Fleet — open and focus it, bring it to front, or close it |
-| `Ctrl+K` | Command palette — search and run any command |
+| `F2` | Toggle Fleet: open and focus it, bring it to front, or close it |
+| `Ctrl+K` | Command palette: search and run any command |
 | `Shift+Tab` | Cycle the session permission mode |
-| `Esc` | Leave the current mode — search, command, or modal |
-| `Ctrl+C` | Clear input, cancel a running turn; press twice to quit |
+| `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).
 
 ---
 
@@ -137,8 +148,8 @@ Full index: [docs/README.md](docs/README.md).
 Settings are layered. Later layers win:
 
 1. built-in defaults
-2. global settings — `~/.goodvibes/tui/settings.json`
-3. project overrides — `.goodvibes/tui/settings.json`
+2. global settings: `~/.goodvibes/tui/settings.json`
+3. project overrides: `.goodvibes/tui/settings.json`
 4. CLI and runtime overrides
 
 Edit them live with `/settings` or the fullscreen `/config` workspace rather than by hand. A few of the most-reached-for keys:
@@ -154,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 |
 
 ---
 
@@ -177,7 +197,7 @@ This includes but is not limited to when a provider moves a model from free to p
 
 Refreshes happen automatically when a new session is started or resumed after the 24-hour catalog TTL expires. For long-running sessions, please ensure that the models are refreshed daily.
 
-Paid and subscription models never auto-switch to a different model — that choice stays yours. When one is exhausted, GoodVibes says so and offers to wait out the cooldown, change model, or move to a free synthetic model. Full failover behavior: [docs/providers-and-routing.md](docs/providers-and-routing.md).
+Paid and subscription models never auto-switch to a different model. That choice stays yours. When one is exhausted, GoodVibes says so and offers to wait out the cooldown, change model, or move to a free synthetic model. Full failover behavior: [docs/providers-and-routing.md](docs/providers-and-routing.md).
 
 ---
 
@@ -193,25 +213,25 @@ 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 — it never spawns a new daemon process itself (`daemon.enabled`, on by default, loopback-bound) — and hosts the HTTP listener when `danger.httpListener` is enabled.
+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`).
 
 Some decisions worth knowing before you read the source:
 
-- **Bun runtime** — native TypeScript execution, fast startup, built-in test runner.
-- **Raw ANSI renderer** — the UI is written straight to the alternate screen buffer, giving direct control over every byte sent to the terminal. Conversation, panels, modals, overlays, and the footer all share that one renderer.
-- **In-process agents** — agents run in the same process rather than over IPC, staying isolated through scoped tool registries and namespaced state.
-- **Typed runtime store** — a plain `zustand/vanilla` store with typed selectors and dispatch paths, reachable from agents, tools, renderer, hooks, channels, and daemon surfaces alike.
-- **Tree-sitter and bundled language servers** — grammars for structural analysis, outlines, and AST-level edits, several embedded as WASM for instant startup; TypeScript, Python, Bash, CSS, HTML, and JSON language servers ship as dependencies, while `rust-analyzer` and `gopls` are fetched on first use with checksum verification.
-- **Backend-first external surface** — the daemon product exposes typed HTTP and gateway methods, so other clients do not reimplement runtime logic.
-- **Crash recovery** — periodic snapshots plus an fsync-per-record append-only transcript journal, replayed at every resume seam.
-- **Render coalescing and a per-message line cache** — same-tick render requests collapse into one composite frame, and transcript growth re-renders only the appended message instead of rebuilding the whole conversation.
+- **Bun runtime.** Native TypeScript execution, fast startup, built-in test runner.
+- **Raw ANSI renderer.** It writes the UI straight to the alternate screen buffer, giving direct control over every byte sent to the terminal. Conversation, panels, modals, overlays, and the footer all share that one renderer.
+- **In-process agents.** Agents run in the same process rather than over IPC, staying isolated through scoped tool registries and namespaced state.
+- **Typed runtime store.** A plain `zustand/vanilla` store with typed selectors and dispatch paths, reachable from agents, tools, renderer, hooks, channels, and daemon surfaces alike.
+- **Tree-sitter and bundled language servers.** Grammars for structural analysis, outlines, and AST-level edits, several embedded as WASM for instant startup. TypeScript, Python, Bash, CSS, HTML, and JSON language servers ship as dependencies, while `rust-analyzer` and `gopls` are fetched on first use with checksum verification.
+- **Backend-first external surface.** The daemon product exposes typed HTTP and gateway methods, so other clients do not reimplement runtime logic.
+- **Crash recovery.** Periodic snapshots plus an fsync-per-record append-only transcript journal, replayed at every resume seam.
+- **Render coalescing and a per-message line cache.** Same-tick render requests collapse into one composite frame, and transcript growth re-renders only the appended message instead of rebuilding the whole conversation.
 
-The TUI consumes the published `@pellux/goodvibes-sdk` platform layer — pinned in `package.json` — for shared contracts, daemon routes, and transports, and keeps the terminal UI, host wiring, and product composition here. Reference consumers of those surfaces live under [`examples/`](examples/reference-operator-client/README.md).
+The TUI consumes the published `@pellux/goodvibes-sdk` platform layer for shared contracts, daemon routes, and transports, and keeps the terminal UI, host wiring, and product composition here. The dependency is pinned in `package.json`. Reference consumers of those surfaces live under [`examples/`](examples/reference-operator-client/README.md).
 
 Source layout, in brief:
 
@@ -226,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,16 +38,16 @@ 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 — the same list `?` renders in the product.
+  The generated, categorized list of every slash command, its arguments, and its description. It is the same list `?` renders in the product.
 
 - [Windows support](windows.md)
   WSL2 as the supported path today, what the native Windows beta binary can and cannot do yet, and the POSIX-assumption blockers ahead of promotion.
@@ -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/README.md

@@ -1,11 +1,11 @@
-## Foundation Artifacts
+## Foundation artifacts
 
 These files are the checked-in canonical artifacts for the current GoodVibes foundation surfaces.
 
-- `operator-contract.json` — typed operator/client contract manifest
-- `peer-contract.json` — node-host / peer contract manifest
-- `knowledge-graphql.graphql` — canonical knowledge GraphQL schema text
-- `knowledge-store.sql` — canonical knowledge SQL schema
+- `operator-contract.json`: typed operator/client contract manifest
+- `peer-contract.json`: node-host and peer contract manifest
+- `knowledge-graphql.graphql`: canonical knowledge GraphQL schema text
+- `knowledge-store.sql`: canonical knowledge SQL schema
 
 Regenerate them with: