V2 TUI terminology and copy decisions #36707

Context

An eight-pass audit of user-visible V2 TUI copy found a small number of repeated product-language decisions behind most inconsistencies. We should settle those decisions together before making broad copy PRs; otherwise each local cleanup will invent its own vocabulary.

The audit covered packages/tui/src at origin/v2 commit 58201a32c1, including home tips, commands, keybinding descriptions, dialogs, prompt input, forms, permissions, transcript rows, tools, status surfaces, notifications, errors, built-in plugins, and copy-bearing tests.

Goal

Agree on one V2 TUI vocabulary and state-language system, then implement it as narrow, reviewable PRs.

This is the gang-grill issue for those decisions. Each section should end with an explicit answer that downstream PRs can apply mechanically.

1. Integration, provider, service, and connection

Current copy uses all three nouns for the /connect journey:

• Connect integration
• Connect a service
• Connect provider
• Connect a provider to send prompts

The V2 model appears to make a useful distinction:

• An integration is something a user connects or authenticates.
• A connection is one saved credential or authorization for that integration.
• A provider is a model source made available through integrations and configuration.

Proposed decision: users connect integrations; model attribution and provider/model references continue to use provider.

Questions:

• Should every /connect entry point say Connect an integration?
• Should a user with one connected integration see Connect another integration?
• Should dialog sections say Popular and Integrations, or use a different grouping?

2. Project, project copy, working copy, workspace, and directory

One create/move/delete flow currently alternates among project copy, working copy, workspace, project directory, and project dir.

Proposed taxonomy:

• Project: the logical codebase.
• Project copy: an alternate checkout managed by OpenCode.
• Directory: its filesystem path.
• Workspace: only if V2 exposes a genuinely distinct durable object that users need to understand.

Questions:

• Is project copy the product term, or should the UI use the more familiar working copy?
• Is workspace intentionally user-facing in recovery flows?
• If workspace is internal, should all active copy remain in project-copy and session language?

3. Session, prompt, message, conversation, and transcript

Current copy rotates among session, conversation, chat, prompt, message, and transcript. Some actions labeled as message actions operate only on user prompts or on boundaries established by them.

Proposed taxonomy:

• Session: the durable work container.
• Prompt: user-authored input and the boundary used by undo, fork, and prompt navigation.
• Message: an item represented in the transcript.
• Session transcript: the full visible ordered history.
• Conversation transcript: only if an export intentionally omits system/session notices.

Questions:

• Should Jump to message, Message actions, and Undo previous message become prompt-specific?
• Does undo include the selected prompt or begin after it?
• Must a session transcript export contain every user-visible notice?
• Should conversation remain acceptable explanatory prose, or should the TUI use session exclusively?

4. Agent, subagent, child session, and background work

The UI presents delegated work as subagents, child sessions, sibling sessions, and bracketed [background] metadata.

Proposed taxonomy:

• Agent: the selected primary behavior.
• Subagent: the delegated actor.
• Subagent session: the navigation target when the underlying session matters.
• In background: an execution state, not a separate actor type.

Questions:

• Should child/sibling topology remain visible anywhere outside diagnostics?
• Should named rows always retain the noun, such as Explore subagent?
• Should [background] become natural language such as in background?

5. Activity panel

The panel called a composer in code and a subagent picker in commands contains completed subagents as well as running shell commands. It is forced open in child sessions.

Questions:

• Is the user-facing name Activity?
• Should it be Live work only after filtering out completed subagents?
• Should completed subagents remain in this panel?
• Should the open/close command be unavailable in child sessions while the panel is forced open?

6. Undo, redo, revert, and restore

One reversible history flow currently uses all four verbs.

Proposed decision: visible controls use Undo and Redo; resulting state uses undone and redone. Keep revert as an internal API term.

Questions:

• Is Undo from here the correct prompt-card action?
• Should redo instructions say Redo rather than restore?
• What exact object should counts name: prompts, messages, or steps?

7. Summarize and compaction

The command palette says Compact session, the alias says /summarize, and transcript notices say Compaction.

Proposed decision: user-facing copy uses Summarize, summary, and states such as Summarizing session, Session summarized, and Session summary failed. Keep /compact and compaction types as internal or compatibility vocabulary.

Question: is compaction intentionally an advanced user-facing concept, or should it disappear from ordinary UI copy?

8. Copy, export, share, and transcript scope

These are distinct operations but current labels blur their objects:

• Copy writes a named artifact to the clipboard.
• Export serializes a session as Markdown, JSON, or event data.
• Share controls public access.

Questions:

• Should the multi-format action be Export session, not Export session transcript?
• Should its dialog be Copy or export session because it supports both destinations?
• Should clipboard success always name the copied object?
• Should sharing copy remain completely hidden while V2 reports the feature as unavailable?

9. Thinking and thought

Current on-screen and exported reasoning labels do not agree.

Proposed decision:

• Thinking: active reasoning.
• Thought: completed reasoning and completed exported content.

Question: do we want this state distinction, or one noun in every context?

10. Tool names and tool-state grammar

Tool rows mix raw IDs, nouns, imperatives, gerunds, past tense, and decorative symbols embedded in text.

Proposed state grammar:

Questions:

• Should primary copy translate Glob, Grep, and WebFetch into actions?
• Should raw tool IDs remain available only as secondary technical details?
• Must every failure be verbalized rather than conveyed by color or icon?

11. Stop, interrupt, kill, cancel, and abort

Current controls use kill for shell commands, interrupt for subagents and sessions, cancel for forms, and aborted in notifications.

Proposed taxonomy:

• Stop: user-facing control for active work.
• Cancel: terminate an unresolved request or form.
• Deny: refuse permission.
• Back: leave a substep without resolving its parent.
• kill, interrupt, and abort: implementation terms unless a semantic difference must be exposed.

Questions:

• Should all active-work controls say Stop?
• If shell kill and model interruption have materially different consequences, what does the user need to know?

12. Permission persistence and denial scope

Current permission copy is factually wrong in two consequential ways:

• Always allow says the grant ends when OpenCode restarts, but V2 saves project-scoped permission rules durably in the database.
• Rejecting one visible permission rejects every pending permission in that session.

Questions:

• Should the durable action say Always allow for this project?
• How can users inspect or remove saved permission rules?
• Should Core rejection change to affect only the selected request?
• If the cascade remains, must the action explicitly say Deny all pending?
• Should Escape ever perform this cascading action without a second confirmation?

13. Form cancellation, dismissal, and acknowledgment

Current form copy uses cancel and dismiss for server cancellation, and alternates between completion and acknowledgment for external URL fields. The API records acknowledgment only; OpenCode does not verify external completion.

Proposed taxonomy:

• Cancel request: terminate the server request.
• Dismiss: close UI without resolving the request, if that behavior exists.
• Back: leave a review or feedback substep.
• Acknowledge / Acknowledged: attest that an external URL field was handled.

Questions:

• Is form cancellation permanent, deferred, or only visual in every producer flow?
• Should Escape say Cancel request whenever it sends form.cancel?
• Should external actions use acknowledgment language everywhere?

14. Error voice and diagnostic detail

Many call sites present a raw backend error as the entire product message. Other errors alternate among Failed to…, Could not…, and noun-first failure states.

Proposed grammar:

• Failed user operation: Could not <action>.
• Stable status: <object> failed.
• Message: user-relevant consequence and a real recovery action.
• Technical detail: existing details view, debug information, or logs.

Questions:

• Is that voice correct, or should all errors use Failed to…?
• When is raw provider text safe and useful in the primary UI?
• Do we need a new details affordance, or are debug information and logs sufficient?

15. Loading, empty, no-match, and error states

Shared selectors and autocomplete currently collapse several states into No results found or No matching items. Some components show loading and failure simultaneously.

Proposed state model:

• Loading <objects>…
• No <objects> available
• No <objects> found
• Could not load <objects> plus a real recovery path

Questions:

• Should stale results remain visible during refresh?
• Should errors always take precedence over empty states?
• Which screens have a real retry action versus requiring close and reopen?

16. MCP status vocabulary

MCP surfaces currently disagree among Needs authentication, Needs auth, Needs registration, Needs client ID, Pending, raw status keys, and raw errors.

Proposed finite map:

• Connected
• Connecting…
• Disabled
• Authentication required
• Client registration required
• Failed, with detail secondary

Questions:

• Is Authentication required preferable to Needs authentication?
• Should compact footers always count MCP server(s), never MCP?
• Is /status an MCP-status screen today, or should it become broader system status?

17. Run and session notifications

Execution lifecycle events settle one busy period; the durable session remains reusable. Current notifications say Session done, including after interruption.

Proposed finite map:

• Run complete
• Run interrupted
• Run failed
• Model response timed out
• Form needs your input
• Question needs your input
• Permission required

Questions:

• Is run the right user-facing noun for one busy period?
• Would OpenCode is ready better describe successful settlement?
• Which sanitized failure reasons are safe for OS notifications?

18. Commands, dialog titles, actions, and hints

Proposed mechanics:

• Command-palette entries begin with imperative verbs.
• Dialog titles use sentence case and name the task or result.
• Stateful controls name the next state: Show sidebar / Hide sidebar.
• Actions name their consequence: Pin / Unpin, Add to favorites / Remove from favorites.
• Keyboard hints use lowercase key first, action second: esc close, enter submit.

Questions:

• Should compact footer actions remain lowercase while buttons and palette commands use sentence case?
• Should OK remain the conventional uppercase exception?
• Should slash-separated key alternatives be replaced with separate hints or or?

19. Mechanical style

Proposed defaults:

• Sentence case throughout.
• Unicode ellipsis for progress and continuation actions.
• No routine exclamation marks.
• Full sentences get punctuation; labels and compact states do not.
• Counts include concrete, correctly pluralized nouns.
• OpenCode names the product; opencode is reserved for literal commands, paths, packages, configuration, and domains.
• Standard abbreviation casing: OK, N/A, API, JSON, MCP, OS, ID, URLs.

Questions:

• Do we approve these as mechanical rules once semantic questions are settled?
• Are there constrained surfaces that should intentionally diverge?

20. Instructional tips policy

The current V2 tips include nonexistent V2 commands and flags, V1 configuration paths and shapes, unavailable sharing/timeline behavior, V1-only doom-loop behavior, and capability claims without a V2 runtime.

Proposed policy: every retained instructional tip must have a cited V2 command, schema, documentation page, or tested runtime behavior at the implementation snapshot.

Questions:

• Should tips be generated from authoritative metadata where practical?
• Should volatile counts and marketing claims be excluded?
• Should unavailable or compatibility-only features ever be advertised in rotating tips?

Proposed implementation slices

After the grill resolves these questions:

1. Remove false V2 tips and stale onboarding claims.
2. Fix consequential permission and form copy.
3. Separate loading, empty, no-match, and error states.
4. Apply approved integration, project-copy, prompt, subagent, export, and status terminology.
5. Normalize transcript, tool, shell, retry, summary, and instruction copy.
6. Normalize contextual errors, MCP/LSP states, notifications, and update copy.
7. Apply mechanical style and focused rendering coverage.

Each implementation PR should update its focused tests and preserve dynamic backend-, plugin-, model-, and user-authored text boundaries.