Commit graph

12 commits

Author SHA1 Message Date
Pascal André
02934f3584
fix(plugins): show installed Git package versions (#1556)
Show the installed package version for Git plugins, keep the full commit
in accessible details, and fall back to seven commit characters. Read
the installed manifest through a bounded daemon-side cache lookup
without changing native update checks; update help in all ten languages.
Verified UI/server typechecks, targeted plugin unit/server/browser
tests, help-reading units, test:help, and isolated OpenCode 2.3 Git
install/check/update.
2026-11-16 14:36:29 +01:00
Pascal André
bb207cfcc6
chore(ui): trim interface copy and multilingual help (#1536)
Trim internal implementation commentary and routine-failure explanations
from the interface and public help in all ten languages. Areas:
Settings, Missions, providers and plugins, projects and remote access,
transcript controls and the 28 help pages.

Keep security and irreversible-action warnings, accessible names, scope
boundaries and facts needed to act. Preserve current dev behavior and
labels; the legacy OpenCode replacement confirmation now identifies its
exact target.

Validated with UI typecheck, ten-locale key and placeholder checks, help
tests, unit contracts and affected browser tests.
2026-11-16 02:34:00 +01:00
Pascal André
0f41f4ec3d
fix(plugins): toggling a plugin replaces its earlier rules instead of appending (#1519)
## Problem

Every Global/Project plugin toggle appended an exact `id` or `-id` rule
to the target configuration file (`appendPluginControlRule`). The file
grew on each toggle: a user's `~/.config/opencode/opencode.json` had
accumulated nine `"-neuralnomads.blender"`/`"neuralnomads.blender"`
pairs, plus `ponytail` and `gpt6-long-context` pairs.

Positive rules are not harmless. In OpenCode 2.3.0 every plugin string
without `-` is one ordered **add** operation
(`packages/core/src/config/plugin/source.ts`, `parse`: `if
(!input.startsWith("-")) return { type: "add", target: input, options:
{} }`). The supervisor treats it as an activation selector only when it
matches a plugin ID already defined or loaded **earlier in the order**,
or is `*`, `prefix.*` or `opencode.*`; otherwise it calls
`modules.load`, i.e. it installs the target as a package
(`packages/core/src/plugin/supervisor.ts`, lines 43–54 at `v2.3.0`).
While the Blender package was reloading, the lone `neuralnomads.blender`
rules were fetched from npm: `failed to load plugin
target=neuralnomads.blender … 404 Not Found GET
registry.npmjs.org/neuralnomads.blender`.

## Change

A toggle now removes the target file's earlier **exact** rules for that
plugin before writing:

1. **remove only**: re-enabling a plugin that is active without its
rules (the `-id` entries go, no `id` is added), or disabling one a
broader rule already disables;
2. else **remove, then append** the requested rule;
3. else the plain append, as today.

The first candidate whose snapshot equals the snapshot appending would
give is written: every control's effective state (no rule = enabled, as
in OpenCode), the displayed Global/Project switches, and every source.
So the effective state stays exactly what the append gave, including
with `*`/`ns.*` selectors, rules in other files, Global and Project,
CodeNomad-managed plugins and the managed **Re-enable** banner (same
mutation).

Never touched: broad selectors, other files, entries the snapshot reads
as **source declarations** (a package named like its ID, e.g.
`"same.id"`), and projections that are not no-op safe
(`{env:}`/`{file:}` placeholders, watcher lag), which keep the plain
append. A re-enable that would leave a lone positive ID read as a
package (plugin absent from the runtime) also keeps the append, because
the snapshots differ.

`replacePluginControlRules` (`plugin-control-document.ts`) edits with
`jsonc-parser`, re-verifies each deleted entry and checks the result
parses to exactly the expected document: comments, other entries,
ordering, indentation, CRLF and the BOM are kept.

## Tests

- New/updated in `plugin-controls.test.ts` (fail on `dev`, pass here — 6
failures on `dev`): the user's accumulated pairs collapse and repeated
toggles keep `[source, "ponytail"]`; a `-acme.*` prefix rule (append
needed to enable, removal only to disable); a Global rule with a Project
toggle; a source named like its ID; managed re-enable with an exact
`-codenomad.automation` in Global and Project; the serialization test
now ends without the disable/enable pair.
- `plugin-control-document.test.ts`: replacement keeps
comments/BOM/CRLF/tabs, removal-only, and refuses a changed entry.
- Unchanged and passing: placeholders, watcher lag, virtual precedence,
managed re-enable past `-*`, WSL document suite.
- `tsc` server, `npm run test:help`.

## Docs

`dev-docs/PLUGIN_CONTROLS.md` (V2 contract with the OpenCode references,
Re-enable, mutation guarantees, tests) and the help's plugin section
(`integrations.md`, English then nine translations): switches replace
the plugin's earlier exact rules in their scope's file.
2026-11-15 21:34:12 +01:00
Pascal André
6027ab2351
feat(integrations): one written, clickable state line per integration (#1509)
Follow-up to #1492 (merged): each integration's Plugins row now says in
words where it stands, and acts when something can be done.

## State line

Under the first line (name, version, switches, **…**), one state line
shows the most important state only. Muted text informs, the theme
accent marks a button, the existing warning colour marks an
incompatibility; no colour is added. Long text is truncated on one line
with the full text in its `title`.

| Family | States, by priority |
| --- | --- |
| Native (e.g. Blender) | part missing → **Install in Blender** ·
outdated → **Update Blender** (both open the existing installation
confirmation) · incompatible (warning, not clickable) · attached → chain
icon + document, a click detaches (title **Detach the conversation**) ·
**Blender closed** · **Blender: no open document** · **No conversation
displayed** · one compatible document → **Attach western_ia.blend** ·
several or not read yet → **Attach…** with the existing document choice
|
| Editor MCP (Affinity) | **Server detected** / **Server not found** |
| API | **Connected** / **Disconnected** |
| Not loaded | **Not loaded**, **Failed to load**, **Non-conforming**,
**Not supported here**, **No answer** |

The automatic attachment at the agent's first use is unchanged. The
triangle indicator and the separate chain button are gone;
`integrationStateLine` (`lib/integration-row-state.ts`) is a pure
function with unit tests for every priority.

![Plugins rows,
light](https://raw.githubusercontent.com/NeuralNomadsAI/CodeNomad/feat/integrations-plugins-row/docs/screenshots/integration-plugins-light.png)
![Plugins rows,
dark](https://raw.githubusercontent.com/NeuralNomadsAI/CodeNomad/feat/integrations-plugins-row/docs/screenshots/integration-plugins-dark.png)

`integration-plugin-row.test.ts` writes one Blender row per state in
light and dark (`integration-state-<state>-{light,dark}.png`) when
`CODENOMAD_INTEGRATION_SCREENSHOTS` is set.

## Native tooltips

Plugins rows used Kobalte tooltips whose skip delay opened every next
tooltip instantly while the pointer crossed the list. Names, the state
line, switches and row actions now use the native `title` like the rest
of the app (~300 controls); a row's details also describe the row
through `aria-describedby`, and controls keep their `aria-label`. The
rule is recorded in `dev-docs/PLUGIN_CONTROLS.md` (Agent conventions).

## Deviations from #1492

- **Open documents are read while the row is shown** (with at least one
offer, again after each integration event) so the line can name the
document before any click. Attaching still reads them afresh, attaches
the shown document only when it is still the only compatible one, and
otherwise opens the choice. #1492 read them only on click.
- **Reinstall in application…** in the row menu when no install or
update is pending, the application open or closed. The Blender plugin
rewrites the part when its files differ and answers "unchanged"
otherwise.
- **Detach moved to the state line**; the row menu now holds the
connection line, **Documentation**, the application part's
(re)installation, the package check, removal and refresh.
- **Unloaded states** get their own short labels (table above). An
unknown binding shows as not attached (attach is offered; a `busy`
outcome is reported).
- **Keyboard trade-off:** focusing a plugin name no longer opens a
visual tooltip; its details reach screen readers as the row's
description, and the state line's full text is its accessible name.

## Tests

- Unit: state-line priorities, link, connection and offer choice,
bindings store, integration stores and API, locales, server routes: 88
pass.
- Browser (real right panel): `integration-plugin-row.test.ts` (each
state's text, tone and colour in light and dark, truncation,
attach/detach/choice, menu documentation and reinstall, native titles,
attach-intent lifetime) with `plugin-controls` and `plugin-sources`: 71
pass.
- `tsc` UI and server, `npm run test:help`: pass.

Strings in all ten locales; help pages (English, then nine translations,
quoting each locale's UI labels), dev-docs (`OPENCODE_INTEGRATIONS`,
`PLUGIN_CONTROLS`) and documentation captures are updated.
2026-11-15 15:09:36 +01:00
Pascal André
c0ea1dd6e9
feat(integrations): manage integrations from their Plugins rows (#1492)
Some checks failed
Publish help / build (push) Waiting to run
Publish help / deploy (push) Blocked by required conditions
Download Caches / seed (macos-15-intel) (push) Has been cancelled
Download Caches / seed (macos-26) (push) Has been cancelled
Download Caches / seed (ubuntu-24.04) (push) Has been cancelled
Download Caches / seed (windows-2025) (push) Has been cancelled
Manage each recognized OpenCode integration from its Status → Plugins row.
Remove the separate per-integration sections and manual attachment picker;
integrations attach conversations through their native first-use contract.

Show catalogue names, package versions, integration-accent switches,
conversation binding and application warnings. The chain button attaches to a
compatible open document or detaches the captured conversation. Revoke pending
enumeration and choices on navigation, invalidation, reconnect and disposal.
Keep guarded application installation and one-shot native actions alongside
existing package controls.
Reads remain demand-driven and refresh on native events and reconnects.

Explicit refresh also retries demanded bindings for the exact displayed
conversation and Location. Preserve integration display and native actions
for inherited, virtual and runtime-only plugins through an unambiguous
runtime identity, separately from writable-source mutation authority.
Keep revision checks, consent revocation and uncertain-outcome handling;
never replay a mutation automatically.

Update help and UI strings in ten locales, documentation and captures.
Cover binding recovery, read-only origins, activation/removal scope and
native-action guards through unit and real-panel browser regressions. Qualify
the projected runtime identities with the isolated official daemon.
2026-11-13 18:32:28 +01:00
Pascal André
f3bf6c4032
feat(plugins): protect CodeNomad-managed system plugins (#1308)
## Problem

CodeNomad's own OpenCode plugins appeared as ordinary plugins with
activation switches, so users could disable an application feature
without knowing it. Filtering by a `codenomad` name or ID would also
hide unrelated third-party plugins and lose loading failures.

## Behavior

- Verified CodeNomad-managed plugins stay outside ordinary plugin rows,
activation switches, package actions and source-removal controls.
- Disabled, failed or loading-unconfirmed managed plugins appear in a
compact warning above the list, with accessible on-demand
error/configuration details.
- **Re-enable** uses the existing activation path: append a positive
exact-ID rule, preserve the disabling rule and unrelated configuration,
and target the disabling Global/Project scope when writable, otherwise
the writable Project override.
- A configuration write does not clear the warning. A fenced native
inventory refresh must confirm active runtime; failed or unconfirmed
loading stays visible. OpenCode is never restarted automatically.

## Approach and edge cases

The server computes `managedBy: "codenomad"` from the authenticated
daemon's discovery root, a validated installer-generated entry and its
SHA-256-addressed payload location/content. The UI filters that marker
rather than recognizing names. Shared installer parsing preserves
retained outside-root storage. Build scripts publish a minimal
exported-ID descriptor inside the hashed payload so absent runtime
entries can still be correlated with exact, prefix and all-plugin
disabling rules, without importing executable code or adding an ID
catalogue.

- Windows paths and file URLs retain their native identity; WSL
translates native directories only for host IO. Reserved WSL UNC
zero-device metadata still requires independent handles, matching
nonzero inodes, regular single-link files, stable bounded reads and
SHA-256 verification. Final file links remain detectable.
- Inherited/external and virtual configuration origins remain distinct
from the writable Project recovery destination; unavailable destinations
offer no mutation.
- Managed failures before exporting an ID retain details, including
native references, without fabricated activation switches or duplicate
warnings. Unproven and third-party local failures retain ordinary path
rows.
- Third-party homonyms remain controllable. The separately packaged
session-pruning TUI companion is not installer-owned merely because its
ID resembles a desktop plugin.
- Concurrent mutation/read reconciliation preserves newer runtime
provenance and failure details; keyboard focus returns to Refresh when a
warning disappears.

## Documentation

Updated `dev-docs/PLUGIN_CONTROLS.md`,
`dev-docs/OPENCODE_COMPATIBILITY.md`, and `docs/help/*/integrations.md`
in all ten supported languages, alongside localized UI labels. The
plugin list is documented on the Integrations help page.

## Validation

Publication rerun on the pushed commits:

- `node --import tsx --test
packages/server/src/opencode/desktop-plugin-artifact.test.ts
packages/server/src/opencode/desktop-plugin-managed.test.ts
packages/server/src/opencode/plugin-controls.test.ts
packages/ui/src/stores/plugin-controls.test.ts` — **96 passed, 0 failed,
0 skipped**. Covers verified managed files, third-party homonyms,
tampering/links, disabled rules, scoped recovery, stale-response fencing
and runtime confirmation.
- `node --import tsx --test --test-concurrency=1
packages/ui/tests/browser/plugin-controls.test.ts` — **28 passed, 0
failed, 0 skipped**. Exercises the real list, warning, Re-enable, native
events, failure details, scope labels and keyboard focus.
- `npm run test:help` — **31 passed**; validates **28 pages in 10
locales**.
- `npm run typecheck --workspace @neuralnomads/codenomad` and `npm run
typecheck --workspace @codenomad/ui` — **passed**.
- `node --import tsx scripts/test-plugin-runtime-native.mjs
<absolute-isolated-cli>` with **OpenCode 2.2.5** — **passed**: native
loading reports the generated `.ts` shim, matches verified installation
provenance, and agrees with the exported-ID descriptor; isolated native
RPC/Form checks also pass.
- With `CODENOMAD_TEST_WSL_PLUGIN_CONTROLS=Ubuntu`, the real
`desktop-plugin-managed-wsl.test.ts` case **passed**, including
zero-device metadata, corruption repair and hard/symbolic-link refusal.
The combined rerun with `plugin-control-document-wsl.test.ts` exceeded
its 180-second local budget after successful document cases; that full
rerun is not claimed complete.
- `git diff --check origin/dev...HEAD` — **passed**. Clean worktree;
exactly the two delivery commits above `origin/dev`, with no rebase,
force push or push to `dev`.
2026-11-06 04:13:30 +01:00
Pascal André
e4b40d85fa
feat(integrations): ship native Status sections and catalogue installation (#1283)
Ship native integration Status sections and catalogue installation by integration ID, including the complete change from #1280. Keep plugin package management in Plugins, per-conversation attachment authority in Status, guarded installation, shared controls, persistent section customization and all ten UI/help locales.

Merge current origin/dev into the feature branch with an ordinary merge, preserving file-reader lifetime and the latest native browser fixture contracts. Resolve conflicts in instance-shell2.tsx, right-panel/core-runtime.tsx, automation-forms.test.ts and session-child-activity.test.ts without weakening assertions or deadlines.

ADMIN-FORCED MERGE AT THE HUMAN'S EXPLICIT REQUEST. The human accepts exactly these two remaining Missions browser failures for this merge:
- mission-schedule-list: fresh-read Start scenario, 15-second SSE setup timeout; reproduced on dev cc5961a797 and established as pre-existing.
- mission-lifecycle-revision: 409 without certified code scenario, 30-second bootstrap timeout; not reproduced by the bounded diagnosis, attribution UNKNOWN, not claimed as pre-existing.

Diagnosis evidence: https://github.com/NeuralNomadsAI/CodeNomad/pull/1283#issuecomment-6617704358
Original full-suite record: https://github.com/NeuralNomadsAI/CodeNomad/pull/1283#issuecomment-6617213011 (1805 pass / 2 fail / 0 skip).

Post-synchronization validation on aba257802949123028741982ba64da988abcbb01: root/server/UI typechecks pass; relevant unit and route suites 142/142; help 31/31; integration browser plus conflicted Forms/session-child suites 144/144; additional file-preview browser regression 5/5. Zero skips or weakened assertions/deadlines.

Foreground gh pr checks --watch completed. Ready-for-review CI run 41737660774 succeeded on this exact head, including all four browser shards, unit tests, compatibility, runtime contracts, native pruning and desktop builds: https://github.com/NeuralNomadsAI/CodeNomad/actions/runs/41737660774 . The preceding run 41737659582 was cancelled; its four cancelled jobs have no steps and remain displayed as fail by gh. These are cancellation records, not executed test failures. The historical two-failure local full result and its limited acceptance remain recorded above.

This exception is limited to this administrative merge. Separate desktop/manual/privacy and publication gates remain scoped independently. No release, tag, npm publication or catalogue change.
2026-11-04 01:36:40 +01:00
Pascal André
f9a97d8a51
feat(integrations): attach native applications and manage plugin sources
Deliver authenticated native application attachment, host installation, binding refresh and revision-fenced plugin source management. Removal warns and confirms possible disruption without coordinating active conversations; local detach remains explicit and uncertain mutations are never replayed automatically.

Integrate accessibility and confirmed schedule-publication corrections, browser-fixture repairs and ownership of readiness writes during shutdown. Preserve the feature branch for the stacked integration-management work.

Admin squash merge explicitly requested by the user before all remaining browser and build checks finished. Targeted and native validation evidence is retained in the PR; this merge does not constitute complete CI, extension, platform or manual pilot acceptance. Remaining qualification continues separately.
2026-11-02 10:47:02 +01:00
Pascal André
794ac20306
feat(integrations): recognise OpenCode integrations from the reviewed catalog and read their state (#1243)
## Summary

Slice C2 of the OpenCode integrations plan: CodeNomad recognises
configured OpenCode integrations from the reviewed catalog and reads
their state. This is the base for attaching an open application to a
conversation (C4) and for the Bundles extension (C3).

- **Catalog** (`opencode/integrations/catalog.ts`): newest
`catalog-v<n>` release of `NeuralNomadsAI/opencode-integrations` (GitHub
releases API, never "latest"), `catalog.json` asset through the API
origin, 256 KiB / 10 s bounds, zod validation, 30 s shared cache with
conditional list requests, last valid catalog persisted and served as
`stale`, `unavailable` with an empty list otherwise. No catalog release
exists yet: the real repository reads as `unavailable` today (no release
was created).
- **Recognition** (`recognition.ts`): registry package (aliases
resolved), plugin ID or exact `-<plugin>` rule (disabled plugins),
`sources.git` prefix; a source designating two integrations or loaded
under another plugin ID is non-conforming.
- **State route** `GET /api/workspaces/:id/integrations?directory=`
(`status.ts`, `integrations.ts`, `routes/integrations.ts`): absent /
inactive / failed / unsupported / non-conforming / unknown / ok; fixed
`status` method under the catalog's RPC ID only, 4 in flight, 8 s each;
full output validation, marker mismatch and path-like `appVersion`
refused; ownership rechecked with `assertCurrent` after the calls;
catalog internals never returned.
- **Plugin add** (AC-P7, D18): recognised `native` integrations are
Global-only (`global-only`, 10 locales); registry and Git specs of one
integration are duplicates.
- **UI store** `stores/integrations-store.ts`: demand reads, 300 ms
coalescing of `rpc.neuralnomads.<app>.*`, `plugin.updated`,
`config.updated`, no polling. Mounted by C4.
- Docs: `dev-docs/OPENCODE_INTEGRATIONS.md`, `PLUGIN_CONTROLS.md`; help
`integrations.md` in English and the nine translations.

## Validation

- `node --import tsx --test
packages/server/src/opencode/integrations/catalog.test.ts` (11 pass,
local release server)
- `node --import tsx --test
packages/server/src/opencode/integrations/recognition.test.ts` (8 pass)
- `node --import tsx --test
packages/server/src/server/routes/integrations.test.ts` (4 pass)
- `node --import tsx --test
packages/server/src/opencode/plugin-sources.test.ts` (11 pass)
- `node --import tsx --test
packages/ui/src/stores/integrations-store.test.ts` (4 pass)
- `node --import tsx scripts/test-integrations-recognition-native.mjs
<opencode 2.2.5 cli>`: PASS (added to the runtime matrix)
- Server and UI typecheck; `npm run test:help` pass.

File sizes: `http-server.ts` ~2500 lines (+7), `index.ts` ~790 (+2),
`pr-build.yml` ~770.
2026-11-01 01:47:20 +01:00
Pascal André
66a85afa1c
feat(plugins): add, remove and show the version of any OpenCode plugin (#1232)
## Summary

Status → Plugins can now **add**, **remove** and **show the version** of
any OpenCode plugin (SCR §4.1, slices C1/U1/D1/Q1, AC-P1…AC-P9).

- **Add**: a `+` icon beside Refresh opens a small `.window-*` popover:
package spec (`--surface-field`), scope (Global default; Project shows
the warning), trust sentence. Registry and remote Git specs only.
- **Remove**: each row's menu gets **Remove from Global/Project** for
declarations in that scope's own write target. `id`/`-id` rules stay;
the package cache is never touched.
- **States**: a just-added source shows **Installing** until
`plugin.list` reports its exact target (then an ordinary active/failed
row). After `PLUGIN_SOURCE_PENDING_TIMEOUT_MS` (120 s) it shows **Not
confirmed** with Refresh.
- **Tooltips**: version, **Update available**, failure + native `ref`,
GUI notice when a `features.gui` package is declared outside Global.

## Implementation

- Server: new `opencode/plugin-sources.ts` + `routes/plugin-sources.ts`
(`POST`/`DELETE /api/workspaces/:id/plugin-sources`), built on
`PluginControls.editConfigDocument` (ownership, scope resolution,
deletion fence, connection fence, lock, atomic replace, JSONC/CRLF/BOM,
WSL). Pure helpers in `plugin-source-document.ts` (npm-package-arg
validation, package identity, verified removal). Types in
`plugin-source-types.ts`. `plugin-controls.ts` only gains `pluginId` on
sources and the `gui` passthrough.
- Errors carry a stable `code`: `invalid-spec`, `local-path`,
`plugin-id` (422), `duplicate`, `stale` (409).
- UI: `stores/plugin-sources.ts`, `components/plugin-source-add.tsx`,
`components/plugin-row-actions.tsx` (replaces
`plugin-package-action.tsx`, memoized item descriptors), i18n part file
in the 10 locales, help in 10 languages, `dev-docs/PLUGIN_CONTROLS.md`
rewritten.

## Deviations to note

- `disabled` state for unloaded sources: `plugin.list` omits disabled
plugins and exposes no package→ID link, so an unloaded configured source
is shown as **Not confirmed** ("may be disabled, or installation not
confirmed"). A disabled package with an exact `-id` rule therefore shows
its ID row (switches) and its unconfirmed source row (Remove items).
Documented in `PLUGIN_CONTROLS.md`.
- AC-P7 "a GUI package is added Global-only, Project refused":
`features.gui` is known only once OpenCode has loaded the package, so
pre-install refusal is not possible. This PR keeps Global as default,
warns for Project, and flags a Project-declared GUI package in its
tooltip afterwards. Native-family Global-only enforcement (D18) waits
for the integration catalogue (later slice).

## Tests

- `node --import tsx --test
packages/server/src/opencode/plugin-source-document.test.ts
packages/server/src/opencode/plugin-sources.test.ts` (13 pass)
- Full server suite: 2931 pass, 0 fail (one load-timeout in
`index.test.ts`, passes alone)
- `CODENOMAD_TEST_WSL_PLUGIN_CONTROLS=Ubuntu …
plugin-control-document-wsl.test.ts` (9 pass, incl. new add/remove)
- `node --import tsx scripts/test-plugin-sources-native.mjs <opencode
2.2.5>`: PASS (loopback fake registry, 404 → failed with `ref`); added
to CI runtime contracts
- UI store tests (45 pass), browser
`plugin-sources`/`plugin-controls`/`plugin-packages` (14 pass), `npm run
typecheck`, `npm run test:help` (31 pass)
2026-10-31 18:43:49 +01:00
Pascal André
1dabb5110f
docs(help): bring the user guide back in line with the current app (#1079)
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.
2026-10-21 14:38:29 +02:00
Pascal André
c0d53f13d4
docs(help): multilingual help site with in-app Help menu and palette entry (#859)
## Summary

A complete public CodeNomad help site in the app's ten languages,
published on GitHub Pages (https://neuralnomadsai.github.io/CodeNomad/)
and opened from the app.

- **Content:** 25 pages in 8 sections (Start, Workflows, OpenCode setup,
Remote access, Customize, Extensions, Desktop, Help), written for
OpenCode power users and covering the current version only. It includes
everything user-relevant from `README.md`, `packages/server/README.md`
(server, network, auth, TLS, Remote Control) and the user-facing
dev-docs, with flags, defaults, labels and safety boundaries checked
against source.
- **Languages:** en, fr, de, es, he (RTL), ja, ne, ru, tr, zh-Hans.
Interface labels reuse each locale's own app strings; native desktop
menu names, code, commands, flags, paths and anchors stay unchanged.
- **Site:** `scripts/build-help.mjs` renders
`docs/help/<locale>/<slug>.md` with translated chrome
(`docs/help/i18n/`), stable `{#id}` anchors identical across locales,
same-article language links with hreflang, a root language chooser, and
a first-party offline per-locale search (Ctrl/⌘+K, substring matching
for CJK, Devanagari and Hebrew, hidden without JS). No analytics or
remote resources.
- **Validation:** `npm run test:help` fails on any missing page or
string, heading drift, broken link/anchor/asset or invalid search
target. `.github/workflows/help-pages.yml` validates PRs and deploys
only from `dev`.
- **App entry points:** one `open-help` command for the palette and a
new **CodeNomad Help** item at the top of the Electron and Tauri Help
menus. It opens the help in the invoking window's UI language through
the existing external opener, falls back to the root URL for windows
without the handler, and reports failures without replay.
- Documents the strict boolean environment-variable rule from #959 and
the updater entry points from #960.

## Review

Delivered as a CodeNomad mission with independent review loops, each to
zero findings:
- English content audit (5 passes, 14 fixes) and technical gatekeeper (2
passes) before translation.
- After translation: QA, UX review, and a final multilingual gatekeeper
(35 translation/label findings fixed, then verified), plus a visual fix
for the search focus ring and a verified sync with #960.

## Validation

- `npm run test:help`: 9/9 (25 pages × 10 locales, strict, including
negative tests); `npm run build:help`: 250 pages.
- `node scripts/test-help-browser.mjs`: 44/44; Playwright: 500 page
visits at 390 and 1280 px, all locales, no overflow, no external
requests.
- UI help-command and desktop-updates browser tests 19/19; help URL unit
tests; Electron menu tests; UI and Electron typechecks; Tauri `cargo
test` 272/272.
2026-10-14 22:44:56 +02:00