mirror of https://github.com/NeuralNomadsAI/CodeNomad.git synced 2026-10-20 19:44:34 +00:00

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

5.2 KiB

Raw Permalink Blame History

Support and source builds

Use the repository for bug reports, current releases and contributions. The troubleshooting guide covers safe recovery before you report an issue.

Report a bug

Open Settings → Info → Diagnostics.
Select Report a bug to open the GitHub issue form.
Review the prefilled version/client information. Add a minimal reproduction, expected behavior and actual result, then submit through GitHub.

The action prefills CodeNomad/OpenCode versions, OS and bounded client/runtime context. It does not prefill listener addresses, workspace paths, credentials or conversation text. Opening the form is not submitting an issue.

If you need more diagnostics, Copy to clipboard or Download .txt produces a separate report. That fuller report can contain local paths and network addresses: review and redact it before attaching it. A screenshot or log excerpt can still contain secrets even when the automatic diagnostic report excludes authentication secrets.

If the GitHub form has incompatible fields, CodeNomad opens a plain issue with the same report information. A temporary failure reading the form does not prevent opening it. You can always use the issue list manually.

Community and releases

Resource	Use
CodeNomad repository	Source, project activity and documentation.
Issues	Search existing reports before opening a reproducible bug or feature request.
Pull requests	Review proposed changes or coordinate a contribution.
Latest release	Stable download artifacts.
All releases	Published previews and release notes.
Neural Nomads	Project organization.
MIT license	License terms.

For issues with native OpenCode configuration rather than CodeNomad controls, consult OpenCode's documentation and upstream releases.

Build from source

Use Node.js 24.20.0, as pinned in .node-version, npm, Git and a compatible OpenCode CLI. Run the commands from a development checkout:

git clone --branch dev https://github.com/NeuralNomadsAI/CodeNomad.git
cd CodeNomad
npm ci --workspaces --include=optional
npm run dev

npm run dev starts the Electron development host. To use Tauri, first install its platform build prerequisites, including the Rust toolchain, then run:

npm run dev:tauri

Development changes affect the development host, not an independently running OpenCode daemon's installed version. Native packaging needs the appropriate target tools; prefer builds on the target OS.

Build and validate

Command, from the repository root	Purpose
`npm run build`	Build the Electron application resources.
`npm run build:tauri`	Build the Tauri application with its native prerequisites.
`npm run build:ui`	Build the browser UI.
`npm run build --workspace @neuralnomads/codenomad`	Build the standalone server and bundled assets.
`npm run build:linux --workspace @neuralnomads/codenomad-electron-app`	Package the Electron Debian release.
`npm exec --workspace @codenomad/tauri-app -- tauri build --bundles appimage`	Package a Linux Tauri AppImage.
`npm run typecheck`	Check the root's configured TypeScript workspaces.
`npm run test:help`	Validate all public-help locales and links.
`npm run build:help`	Build the standalone public help into `dist/help`.

The help build does not need a running CodeNomad or OpenCode service. See BUILD.md for packaging details and CONTRIBUTING.md for scoped validation and PR conventions; use the scripts actually present in the target package.

Package map and contribution

Package	Responsibility
`packages/server`	Workspace/API/Git controls, OpenCode connection, auth, events and speech.
`packages/ui`	SolidJS workspace, controls, localization and browser help entry point.
`packages/electron-app`	Electron windows, native integration and packaging.
`packages/tauri-app`	Tauri windows, platform integration and packaging.
`packages/remote-tunnel`	Backend-side OpenTunnel transport runtime.

Discuss the scope in the relevant issue before implementing overlapping work.
Branch from dev and keep the change focused.
Run the checks for the affected area, update user help alongside behavior, and target your PR at dev.

Public help sources live in docs/help/<locale>/. Preserve each English heading's explicit ID, level and order across translations; translated headings must not break deep links. The help maintenance contract describes strict completeness checks and the static publishing pipeline.

5.2 KiB Raw Permalink Blame History