mirror of
https://github.com/NeuralNomadsAI/CodeNomad.git
synced 2026-11-16 13:11:03 +00:00
Trim repetition and historical commentary in developer documentation and agent guidance without changing contracts or behavior. Areas: runtime and ownership, Missions, memory, browser and transcript workflows, settings, repository skills and bundled Design recipes. Preserve current dev contracts, safety boundaries and agent rules. Proposed design changes remain outside this editorial pass. Validated with Design unit and bundle tests, isolated native skill discovery and loading, palette quality, UI typecheck and help tests.
313 lines
20 KiB
Markdown
313 lines
20 KiB
Markdown
# Public user help
|
|
|
|
The guide covers CodeNomad with OpenCode V2. Assume readers already know OpenCode:
|
|
document CodeNomad's controls, workflow differences and state/scope boundaries
|
|
instead of teaching agents, prompts, Git or MCP. Keep pages focused and link
|
|
to the official V2 docs for native configuration details.
|
|
|
|
## Sources and navigation
|
|
|
|
- `docs/help/site.json`: the ten app locales and the ordered section/page list.
|
|
Section ids are `start`, `workflows`, `opencode-setup`, `remote-access`,
|
|
`customize`, `extensions`, `desktop`, `help`. The approved 28 pages each appear once; `index` comes first,
|
|
then `download`, which the header **Download** link (`download.label`) opens on every page. The `help`
|
|
section ends with `support` (bug reports and source builds) and `sponsor` (**Support CodeNomad**:
|
|
why and how to fund development).
|
|
- `docs/help/<locale>/<page>.md`: one H1 supplies the title and navigation label.
|
|
Locales are `en`, `fr`, `de`, `es`, `he`, `ja`, `ne`, `ru`, `tr`, `zh-Hans`.
|
|
- `docs/help/i18n/<locale>.json`: translated site chrome, section labels, release strings, download-button and funding labels.
|
|
Keep the same non-empty keys in every language. Page titles belong in Markdown, not here.
|
|
- `docs/help/help.css`: square, responsive chrome, light/dark palettes and
|
|
logical properties for Hebrew RTL. Never import application styles/runtime.
|
|
|
|
Every H2/H3 (and deeper heading, if used) needs an explicit ASCII kebab-case id:
|
|
|
|
```md
|
|
## Answer requests {#answer-requests}
|
|
### Permissions {#permissions}
|
|
|
|
[Another page](permissions.md#answer-requests)
|
|
[This page](#permissions)
|
|

|
|
```
|
|
|
|
The builder strips the suffix and assigns the id. Do not translate or reorder
|
|
ids: every translated page must have exactly the English ordered (level, id) list.
|
|
The single H1 is the page title, without an explicit id; an H1 `{#id}` is an error,
|
|
never silently discarded. Link to an H2 section instead.
|
|
Ids are unique within a page; `content`, `help-query` and `help-results` are reserved
|
|
for site chrome. Avoid raw
|
|
HTML headings or images: Markdown supplies the metadata needed for validation.
|
|
|
|
Inter-page Markdown links become same-locale HTML links with their anchors
|
|
intact. HTTPS links stay unchanged. Relative repository-reference links outside
|
|
the guide become GitHub links; relative images (whose real path must stay inside
|
|
the repository) are copied once into shared `assets/media/`, not fetched from
|
|
remote hosts. Use paths relative to the source
|
|
page, including the locale directory.
|
|
|
|
## Release links and generated blocks
|
|
|
|
`docs/help/downloads.json` (untranslated, read from this repository even with
|
|
`--content`) lists the stable release assets in display order, Tauri first: each
|
|
entry has `id`, `platform` (`windows`/`macos`/`linux`), `host` (`tauri`/`electron`),
|
|
`arch` (`x64`/`arm64`) and an asset-name `template` with one `{version}` (the tag
|
|
without its `v`). Templates must match the real asset names of a published release.
|
|
|
|
`[label](release:<id>)` links to that asset. With release data the link is the
|
|
exact download URL followed by `<span class="download-size">`, decimal megabytes
|
|
formatted for the page locale; without release data (local and pull-request builds)
|
|
every release link opens `releases/latest` without a size. An id missing from
|
|
`downloads.json` is an `unknown-release-asset` problem.
|
|
|
|
A directive is a top-level paragraph containing only `{{name}}`; the builder
|
|
replaces it with generated HTML that has no headings and never becomes the meta
|
|
description. `{{release}}` renders a `release-line` paragraph from the
|
|
`release.published` chrome string (version and a long UTC date for the page locale)
|
|
or, without release data, `release.unavailable` linked to the latest release.
|
|
`{{download-button}}` is allowed only on `download.md` (elsewhere `misplaced-directive`)
|
|
and makes that page load `help-download.js` (see below). It renders a hidden
|
|
`div.download-primary` holding one hidden `data-download-os` block per target
|
|
(`windows`, `macos`, `linux`, `mobile`), each with its final `a.download-main` label and
|
|
href: the Tauri Windows x64, macOS arm64 and Linux x64 assets from `downloads.json`
|
|
with a detail line and size, a secondary Intel Mac link (macOS x64), and `mobile.html`
|
|
for phones and tablets. Without release data the desktop targets open `releases/latest`.
|
|
Labels are the `download.*` chrome strings; search excerpts omit the hidden block.
|
|
`{{tour-video}}` is allowed only on `index.md` and renders `figure.tour`: a silent
|
|
`<video autoplay muted loop playsinline controls preload="metadata">` (`tour.label` as
|
|
`aria-label`) whose poster and single `<source>` are `docs/screenshots/codenomad-tour-poster.jpg`
|
|
and `codenomad-tour.mp4`, copied to `assets/media/` like images; an `<img>` of the same
|
|
poster (`tour.poster` alt); and a caption linking `tour.caption` to the full YouTube tour.
|
|
The source's `media` is `(prefers-reduced-motion: no-preference) and (min-width: 721px)`,
|
|
so narrow screens and reduced motion download no video; `help.css` hides the player and
|
|
shows the image under the exact complement of that condition and in print, so no
|
|
player without a video appears. A browser that loads a narrow page and is then widened
|
|
keeps that sourceless player until reload. Keep the clip silent H.264 4:2:0, 1280x720,
|
|
40-50 s, faststart and at most 3.5 MB, and the poster a 1280x720 JPEG of at most 200 KB;
|
|
provenance and encoding live in `docs/screenshots/README.md`.
|
|
`{{funding}}` is allowed only on `sponsor.md` and `download.md` (`#support-development`, the
|
|
download page's last section, never gating the download) and renders `ul.funding`: one outlined
|
|
44px button per channel of `docs/help/funding.json`, in file order, labelled `funding.action`
|
|
with the channel name in `<bdi>`, followed by `funding.recipient` naming who receives the money.
|
|
With an empty `funding.json` a page using it is a fatal `missing-funding` problem.
|
|
Each directive appears at most once per page (`duplicate-directive`) and every
|
|
translation of a page carries the same directives as English (`directive-mismatch`).
|
|
Any other `{{` in rendered text, including a directive inside a list item, table
|
|
cell, quote or sentence, is an `unknown-directive` problem; inline code and code
|
|
blocks are exempt, so samples stay writable. All of these problems are fatal.
|
|
|
|
A paragraph containing nothing but one link to a help page (`[Download CodeNomad](download.md)`)
|
|
gets `class="action"` and renders as the accent button, full width under 720px. Only
|
|
the home page uses one; write such a lone link elsewhere only for a primary call to action.
|
|
|
|
Release data is `{ tag, version, publishedAt, assets: { <id>: { url, size } } }`,
|
|
passed as `buildHelp({ release })` or `--release <file>`; the builder never makes
|
|
network requests. It revalidates the data and throws on any deviation: exactly
|
|
these keys, a `vMAJOR.MINOR.PATCH` tag with `version` equal to it without `v`, a
|
|
real UTC timestamp, exactly the `downloads.json` ids, each URL equal to
|
|
`https://github.com/NeuralNomadsAI/CodeNomad/releases/download/<tag>/<asset>`
|
|
with URI-encoded components, and safe positive integer sizes. Version, date and
|
|
size are escaped before they fill chrome templates. Tests use the offline fixture
|
|
`scripts/fixtures/help-release.json` (v1.0.0) and fail if `fetch` is called.
|
|
|
|
## Funding channels
|
|
|
|
`docs/help/funding.json` (untranslated, read from this repository even with `--content`) lists
|
|
the funding channels in display order: each entry has exactly `id` (unique kebab-case), `name`
|
|
and `recipient` (non-empty display text, escaped) and `url`. URLs must match an allowlisted
|
|
canonical form, currently only `https://github.com/sponsors/<login>` (a valid GitHub login,
|
|
lowercase host, no credentials, port, query, fragment or trailing path); add a pattern to
|
|
`FUNDING_URLS` in `scripts/build-help.mjs`, with tests, before listing another platform.
|
|
Adding a channel needs no retranslation: pages reach channels only through `{{funding}}`.
|
|
Tests may inject channels with `buildHelp({ funding })`, validated like the file. The header
|
|
**Sponsor** link (`funding.label`, after **Download**) opens `sponsor.html` on every page only
|
|
when at least one channel exists and the `sponsor` page is built. Tests allow sponsorship URLs
|
|
(GitHub Sponsors, Open Collective, Liberapay, Polar, thanks.dev, PayPal, Patreon, Buy Me a
|
|
Coffee, Ko-fi) only inside the generated block, which must list exactly `funding.json`, and only
|
|
on `sponsor.html` and `download.html`; never hand-write a funding link in Markdown.
|
|
|
|
## Translation workflow
|
|
|
|
Write/update English first, then copy the page to the other locale directories
|
|
and translate its prose, H1 and link labels while preserving filenames, heading
|
|
ids and local link targets. Use the app's own terminology where relevant.
|
|
Add a new page to `site.json` and provide it in every locale.
|
|
|
|
Missing translations still build: the selected language's chrome remains, a
|
|
translated notice explains the fallback, and the English article has `lang="en"`
|
|
and `dir="ltr"`, including within Hebrew pages. The page's language menu and
|
|
`hreflang` alternates retain its identity in every language. An absent translation
|
|
offers a contribution link for that locale; existing pages link to their editor.
|
|
|
|
The full check fails for missing translations, heading-id drift, unresolved
|
|
links/anchors/images, duplicate or missing heading ids and invalid page
|
|
structure. `--locale en` checks English alone while translation is pending.
|
|
|
|
## Build and check
|
|
|
|
```sh
|
|
npm ci --ignore-scripts
|
|
npm run test:help -- --locale en
|
|
npm run test:help
|
|
npm run build:help
|
|
node --import tsx --test packages/ui/src/lib/help-url.test.ts
|
|
node scripts/test-help-browser.mjs
|
|
```
|
|
|
|
Output is `dist/help/<locale>/<page>.html`, with `index.html` also serving each
|
|
locale directory. Shared assets live under `dist/help/assets/`. Serve `dist/help`
|
|
with any static HTTP server; no backend, credentials or OpenCode service is
|
|
needed. The builder uses the `marked` dependency. To exercise a
|
|
throwaway source tree without editing real content:
|
|
|
|
```sh
|
|
node scripts/build-help.mjs <output-directory> --content <source-directory>
|
|
node scripts/build-help.mjs <output-directory> --release scripts/fixtures/help-release.json
|
|
node scripts/test-help.mjs --locale en --content <source-directory>
|
|
```
|
|
|
|
The source override needs its own `site.json` and locale directories; site CSS,
|
|
logo and chrome strings still come from this repository. Builder failures are
|
|
fatal except absent translations (warnings); heading drift is fatal in both build
|
|
and validation. Rebuilds delete only paths recorded by the previous build in
|
|
`.help-output.json`, preserving unrelated files in a caller-supplied output directory.
|
|
Tests create and remove only their own temporary directories.
|
|
|
|
The optional Playwright check renders English, Hebrew, Nepali, Japanese and Chinese
|
|
at desktop/intermediate/mobile widths in light/dark mode with all four header items
|
|
(Download, Sponsor, GitHub, language) inside the viewport, checks project-site links,
|
|
the funding buttons (exact label, square 44px targets spanning 390px screens, English and Hebrew),
|
|
search states/keyboard/IME, skip-link focus and the script-free fallback, the home tour
|
|
(muted playback at 1440px; at 720px, 390px and with reduced motion an empty `currentSrc`,
|
|
no clip request and the visible poster; 16:9 boxes without overflow), and writes captures to `%TEMP%/codenomad-help/` (the OS
|
|
temporary directory on other systems). It accepts the same `--content` override.
|
|
|
|
Locale navigation and articles need no JavaScript. The root chooser has a tiny inline script,
|
|
hash-authorized by its CSP, to select the best supported `navigator.languages`
|
|
match (including `zh-*` → `zh-Hans` and `iw` → `he`). Plain language links work
|
|
with scripting disabled. Never add analytics, remote fonts or remote runtime
|
|
requests. Navigation/alternate links work under the GitHub project-site path.
|
|
|
|
Article pages load first-party scripts only, copied unchanged to assets and allowed
|
|
by article CSP (`script-src 'self'`). Tests require exactly `help-search.js` on every
|
|
page plus `help-download.js` on `download.html` alone, and reject any other, inline or
|
|
remote script, `on*` attributes and inline styles. The build records both scripts in
|
|
`.help-output.json` like every owned output file.
|
|
|
|
The article CSP adds `media-src 'self'` for the home tour alone. Tests allow exactly its
|
|
`<video>` and `<source>` on `index.html`, reject media elsewhere and any iframe, audio,
|
|
embed, object or track, resolve `poster` like every local `href`/`src`, and check the
|
|
clip and poster files against their budget by parsing the MP4 boxes and JPEG header.
|
|
Never embed YouTube or other remote media; link to it.
|
|
|
|
`docs/help/help-download.js` makes no requests and never probes the architecture.
|
|
The named pure `detectDownloadPlatform(navigator)` checks phones and tablets first
|
|
(client-hint `mobile`, Android, iPhone/iPad/iPod, and iPadOS's Mac platform with more
|
|
than one touch point), then `navigator.userAgentData.platform`, then the user agent and
|
|
`navigator.platform`; Windows on ARM gets the x64 build, while ChromeOS, ARM Linux and
|
|
unknown systems get nothing. The script reveals the matching block and its container only
|
|
when that link has an href and a label, so without JavaScript, on failure or for an
|
|
unknown system the button stays hidden and the always-rendered table is the download
|
|
path. Print hides the button; under 720px it spans the article. The detector and reveal
|
|
tests (`scripts/test-help-download.mjs`, imported by `test-help.mjs`) run the script in
|
|
a `node:vm` context against the real built page with a minimal fake DOM; the Playwright
|
|
check verifies one revealed platform, its 44px target and the no-JavaScript state.
|
|
|
|
`docs/help/help-search.js` (`connect-src 'self'`) loads only the current locale's build-time `search-index.json`; entries contain
|
|
article title, explicit heading id/text and a short section excerpt. Tests resolve
|
|
every result to its real HTML anchor. Normalized substring matching supports CJK,
|
|
Devanagari and Hebrew without libraries or remote requests. Ctrl/Cmd+K focuses,
|
|
arrows select, Enter follows the real link, Escape dismisses/restores focus;
|
|
composition and browser Ctrl/Cmd+F are untouched. Empty/no-results/load-failure
|
|
states are localized. Search is hidden without JS. Desktop navigation and outline
|
|
use CSS-exclusive wide views; narrow layouts use native collapsed disclosures,
|
|
so responsive defaults require no extra script. Tables/code scroll locally, inline
|
|
code/key chords isolate LTR, and selected rows follow the app's 40%/50% accent-ink tint.
|
|
|
|
## Application entry points
|
|
|
|
Electron and both Tauri Help-menu branches put **CodeNomad Help** first, then
|
|
**Support CodeNomad**, before the update/About items. The hosts send `open-help`
|
|
or `open-sponsor` to the primary renderer; its palette-command dispatch executes
|
|
the localized **Open help** or **Support CodeNomad** command and uses the current
|
|
UI locale. Browser and remote users can run the same commands from the palette;
|
|
Settings → Info's Support CodeNomad card opens the same `sponsor` page.
|
|
|
|
`packages/ui/src/lib/help-url.ts` owns the base URL and locale→path mapping
|
|
(`helpUrl(locale, page, anchor)` accepts ASCII kebab-case page names and section ids, falling back to the locale home for an invalid page and omitting an invalid anchor). Contextual `SettingsInfoTip.help` destinations use published page/section pairs checked across all ten locales by `lib/help-url.test.ts`;
|
|
`openExternalUrl` opens the system browser on native hosts (Electron's
|
|
new-window policy handles `window.open` and reports asynchronous opener failures
|
|
through a visible host error) or a separate browser tab. Tauri remote windows
|
|
have no generic opener/native capability: their owned new-window/navigation policy
|
|
hands only credential-free HTTPS URLs under `https://neuralnomadsai.github.io/CodeNomad/`
|
|
on port 443 to the system browser, denying other external targets and native guests.
|
|
New-window callbacks recheck the registered window generation before opening.
|
|
Help never
|
|
navigates the application renderer. Preferences/remote/loading windows without
|
|
a primary menu listener fall back to the root chooser for help and to the
|
|
English `sponsor` page for Support CodeNomad (Tauri `SPONSOR_URL`). The custom Windows
|
|
titlebar's `help` menu opens the same native submenu.
|
|
Malformed locale tags are rejected before prefix mapping. Opening failures use
|
|
localized renderer alerts or a native host error; actions are never replayed.
|
|
Treat `window.open` returning null with `noopener` as success.
|
|
|
|
Search suppresses Chromium/WebKit's native search-cancel affordance; the single
|
|
labelled Clear button retains its 44px touch target.
|
|
|
|
## Publish on GitHub Pages
|
|
|
|
Pages is enabled with **GitHub Actions** as the source at
|
|
**https://neuralnomadsai.github.io/CodeNomad/**.
|
|
|
|
`.github/workflows/help-pages.yml` runs on `dev` pushes, manual runs, pull requests
|
|
and every completed **Release Binaries** run (`release.yml`, pushes to `main`), so a
|
|
new stable release republishes the download links. It deploys only from `dev`
|
|
(pushes, manual runs from `dev` and accepted release events, whose `github.ref` is
|
|
the default branch). Help sources, screenshots, images, help scripts, the
|
|
`scripts/fixtures/help-*.json` fixtures, shared URL module, manifests/lockfile and
|
|
`.node-version` trigger the push and pull-request runs. No extra hosting secret is needed.
|
|
|
|
- A release event is accepted only when that run succeeded and ran for a `push` to
|
|
`main` of this repository; the job gate is checked before checkout. Accepted
|
|
events check out the trusted `dev` sources; never use the release run's commit
|
|
(`head_sha`) or artifacts.
|
|
- The build job has `contents: read` and a checkout without persisted credentials;
|
|
only the resolver step receives `GH_TOKEN: ${{ github.token }}`. Deployment alone
|
|
has `pages: write` and `id-token: write`.
|
|
- One workflow-level `help-pages-production` concurrency group serializes checkout,
|
|
resolution, build and deployment for every `dev` run without cancelling the one in
|
|
progress. Pull requests use per-PR groups that cancel superseded runs; rejected
|
|
release events use a per-run group, leaving a pending production run in place.
|
|
- Pull requests run `npm run test:help` and build without release data, skipping
|
|
resolution and deployment.
|
|
|
|
Every other run calls `scripts/resolve-help-release.mjs "$RUNNER_TEMP/help-release.json"`
|
|
after the tests, then `build-help.mjs --release` on that file. The resolver runs only
|
|
when `GITHUB_ACTIONS` is `true` and `GH_TOKEN` is set, so a local build cannot reach
|
|
the API; locally, omit `--release` or pass the fixture. It lists every release page
|
|
(`per_page=100`, at most 10 pages, 20-second timeout per request, no redirects) and
|
|
follows a `Link` `rel="next"` only to `https://api.github.com` release listings of
|
|
this repository. `selectRelease(releases, downloads)` is pure. Only non-draft,
|
|
non-prerelease `vMAJOR.MINOR.PATCH` tags are candidates. It rejects malformed
|
|
entries or assets, a candidate's invalid `published_at`, duplicate candidate tags
|
|
and duplicate asset names, orders candidates by `published_at` and picks the
|
|
newest where each `downloads.json` asset is exactly one
|
|
`uploaded` asset with a positive size at the expected download URL. Newer stable
|
|
releases still missing assets (a release exists before its uploads finish) produce a
|
|
`::notice::` naming the missing files, and the previous complete release is used.
|
|
API, authentication, pagination or validation failures and the absence of any
|
|
complete release exit nonzero with an `::error::`: the build fails and the previously
|
|
published site stays live. The written file is revalidated with `validateRelease`
|
|
before the resolver exits successfully. It reads release metadata only; never add
|
|
binary downloads to it.
|
|
|
|
Tests run the resolver offline against trimmed recordings of the real listing,
|
|
`scripts/fixtures/help-release-api-page1.json` and `help-release-api-page2.json`,
|
|
with an injected fake `fetch`; the recorded `v1.0.0` must resolve
|
|
exactly to `scripts/fixtures/help-release.json`. A workflow test parses
|
|
`help-pages.yml` and checks the trigger, gate, permissions, token scope, concurrency
|
|
and pull-request path.
|
|
|
|
To republish by hand (for example after a release run whose help build failed), run
|
|
the workflow manually from `dev` or push a help change to `dev`.
|
|
The full multilingual check intentionally blocks publishing incomplete translations.
|