1dabb5110f
docs(help): bring the user guide back in line with the current app The help was written on 2026-10-14 and about forty user-visible changes merged since without touching it, so several pages described controls that no longer exist: Missions still listed four playbooks and a Save step for preferences that now save on each change, the depth editor kept its old names, notifications still had their former switches, and voice input pointed to a microphone button that is not in the composer. Every English page was re-checked claim by claim against the current labels (English UI messages) and behaviour, then the nine translations were updated to match, using each locale's own UI labels. Notable corrections: Missions (Compare two models, autosaving defaults with Apply to / Global / Reset, Subsession nesting depth, prepared hand-offs, retired-task interrupts, the named causes of "Mission Control is unavailable", standalone server support); conversations and history (reasoning/tool durations, token lines adding up the cleanup selection, presets including Nothing, timeline markers following Message content, in-place reveal of long text, Open in session, focus after send, Queue message / Steer now, Retrying); settings (notification routing table and defaults, Stats, Mode, info tips, Server setting badge, localized native menus); shortcuts (72 actions, Clear shortcut, Ctrl/Cmd+K); voice (More actions entries, Save status); files (live Workspace refresh, Show 200 more); OpenCode, install, server and updates (2.1.1 recommended, OpenCode 2 beside an older installation, version card first, private loopback listener for Missions, preview releases offered once all builds are published); providers, integrations, browser, SideCars, desktop and remote pages. Translations also repaired older drift, mainly the project-tab closing passages. The Chat settings table header (Default state, its title, item column, the thinking row and its accessible label) was still English in eight locales; it is now translated so the help can cite what users see. AGENTS.md now asks every PR changing user-visible behavior to update the affected help pages in the same PR, since CI validates structure and links but not whether the text still matches the UI; it also corrects the needs-input notification default. USER_HELP.md no longer claims native menus stay English. Validation: npm run test:help (all ten locales, 25 pages, heading ids unchanged), a full help build, and the i18n and transcript-visibility unit tests.
6.4 KiB
Native integrations
CodeNomad exposes OpenCode's native MCP connections, plugin activation, skills and custom commands. These run on the execution host. They are separate from sandboxed panel Extensions and SideCars.
Choose the right control
| Integration | Where to act | What the control changes |
|---|---|---|
| MCP server | Status → MCP Servers | Native connection at the displayed Location; does not install a server. |
| Native plugin | Status → Plugins | Persistent Global or Project activation rule; for a package plugin, an explicit check or update of that package. Does not install or remove packages. |
| Skill | Composer @ menu |
Explicit attachment to the next prompt in the conversation's Location. |
| Custom command | Composer / menu |
Runs a command exposed by OpenCode for that Location. |
Configure/install the integration using OpenCode's supported configuration and CLI first. Installing a package, declaring its source, enabling its rule, connecting a service and making its tools available are separate steps. Native integrations have their host process's privileges, subject to OpenCode permissions; they are not sandboxed HTML panels.
Connect or disconnect MCP
- Configure the MCP server on the OpenCode execution host using OpenCode MCP documentation.
- Open Status → MCP Servers for the project.
- Use the switch beside the server to connect or disconnect it. Wait for the connection indicator to settle.
The switch calls the native connection API for the reported Location, not a device-local installer or a per-window visibility preference. Other clients using that Location can observe the connection change. Disconnecting does not remove the server declaration or uninstall its executable.
If no server appears, verify the active Location and its native configuration. If connection fails, inspect the server's configuration, required environment and native authentication flow; do not assume the switch completes OAuth. Recheck status after reconnecting. Use explicit configuration reload only when necessary, with the disruptions described in OpenCode setup.
Activate plugins at Global or Project scope
- Install/declare the native plugin with OpenCode; then open Status → Plugins.
- Hover or focus its name to inspect source, runtime failure and configuration-target details.
- Toggle Global or Project deliberately. Wait for the write and use Refresh plugin controls if the state is unclear.
- For a plugin installed from a package, use the icon beside its name. Its menu names the exact operation: Check updates for the package, or Update it once a newer version is found.
Global targets the connected daemon's discovered global configuration. Project targets configuration within the active Location, not an inherited ancestor file. A later Project rule can override Global; the Global switch still shows the Global rule rather than pretending to be the final Project state. With no Project rule, Project inherits the resolved Global state.
These switches append exact activation rules while preserving source declarations and unrelated configuration. They do not edit plugin options, install packages or remove files. Built-in OpenCode plugins are not offered as user activation switches. Project is disabled when its target cannot be safely separated from Global or would escape the active Location.
A package update changes that package in OpenCode's shared cache for every Location using it, as its tooltip states; it does not change activation rules, restart OpenCode or reload configuration. Local, built-in and SDK-provided plugins have no package action. A package that fails before reporting its plugin ID is listed by its package name, with the failure in its tooltip and check/update actions but no activation switches. A failed check or update is reported and never retried automatically.
The surface retains its last snapshot while hidden and revalidates when shown, on native changes/reconnect and on explicit refresh. A saved rule and live runtime availability can briefly differ. If a plugin remains unavailable, inspect its tooltip and native configuration before choosing Reload OpenCode configuration; that action affects all loaded Locations, not just this plugin. Malformed configuration or a concurrent edit is not silently overwritten: resolve it, refresh and retry explicitly.
Attach skills
- Type
@in the composer, search the Location's available skills and select one. - Check its removable attachment alongside files/agents; remove it before sending if it is not intended.
- Send the prompt. Skill labels remain with the sent message.
Selection attaches the native skill ID and removes the @query token; it does not paste the instructions into the visible draft. Sending clears the composer selection, not instructions already stored by OpenCode with that message. Removing an attachment cannot undo an earlier send.
Skill availability comes from the conversation's Location, not a global CodeNomad skill catalogue. If the list cannot load, close and reopen the picker to retry; if empty, check native discovery/configuration. See OpenCode skills documentation and Conversations.
Run custom commands
- Type
/in the composer and choose an available native command. - Supply its arguments and check Agent, Model and Thinking before submitting as appropriate for that command.
- Inspect the resulting conversation rather than repeatedly submitting if acknowledgement is unclear.
Commands are discovered from OpenCode for the active Location. Their own native definition can choose execution behavior; the menu is not a package installer or an unrestricted configuration editor. CodeNomad applies the profile's session environment before native custom-command submission; a failed environment update blocks the send. /btw is CodeNomad's separate ephemeral question flow, not an ordinary custom command.
For command definitions and native configuration inheritance, use OpenCode commands documentation. After configuration changes, refresh/reopen the relevant surface first; use explicit configuration reload only if the runtime still needs it. Never replay a possibly admitted command solely to refresh its display.