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.
## Summary
- Extend the existing `SettingsInfoTip` with `help?: { page: string;
anchor?: string }`; retain short hover/focus explanations and open
matching localized help externally on click, Enter or touch.
- Reuse `helpUrl` and `openExternalUrl`, guard page/anchor syntax,
preserve containing controls and disclosures, and show the existing
localized help error without replaying failed actions.
- Carry destinations through existing choice rows, behavior settings and
core Status metadata; document the reusable pattern and update the
settings guide in all ten languages.
## Linked inventory
- General: automatic subsession expansion, keep-awake, Memory, Tidy up
and memory-review warning.
- Advanced: whitespace-only changes and session environment variables.
- OpenCode: startup launch.
- Providers: image generation and image storage.
- Notifications: On screen, History and System column tips.
- Speech: provider, separate providers, shared/input/output base URLs,
playback mode, output format, playback test and prompt voice input.
- Status: Tokens, Yolo mode, Usage, Background Shells, MCP and Plugins.
Mission creation/scheduling/depth/preferences belong to the separate
form change, which can use the shared prop directly. Dynamic mission
budget, attention and diagnostics tips retain their information-only
purpose. Existing `SettingsInfoLink` and integration `InfoPopoverButton`
explanations retain their actionable/runtime-specific popovers; sidebar
Info navigation and Info-card heading icons keep their distinct purpose.
## Validation
- `npm ci` in the isolated checkout.
- UI typecheck.
- URL/section checks: every literal contextual destination resolves in
all ten locales, including `zh-Hans`.
- Behavior and right-panel registry tests: 14 passed.
- Full help suite: 31 passed, validating 28 pages × 10 locales.
- Real Solid browser gesture and relevant settings regressions: 56
passed (new shared-tip cases, startup launch, General/appearance,
Memory, notifications and help-command routes). All eight new
gesture/native-route cases pass.
- The fixture-wiring audit reports two existing WebKit fixtures without
the required exemption/navigation-budget wiring; those files and the
audit inputs are unchanged from `origin/dev`.
## Scope
No Mission form/tree edits, new dependencies, URL registry, plugin
extension point or duplicated info component. Visible explanations and
opener errors reuse existing translations.
## Independent review and CI
Round 1 found a translation-readiness race in the browser test. The test
now waits for the real localized info-link label before activating it.
Round 2: **No findings**.
Current `origin/dev` is merged. CI has baseline failures in the
unchanged binary-build ordering expectation and Cargo lockfile; the unit
failure reproduces locally and the affected inputs match `origin/dev`.
The existing fixture-wiring audit likewise reports only unchanged WebKit
files. These are tracked in the PR discussion separately from
contextual-help validation. Additional platform jobs remain
queued/running; admin merge is explicitly authorized for this change.
## Real component capture

Playbooks were opaque: the Mission editor showed one sentence per playbook,
and nothing told users which steps and roles a playbook runs, when they are
asked something, what CodeNomad actually enforces, or which instructions
the agents receive.
A new help page, playbooks.md (ten locales, linked from the Missions help),
explains the shared rules every playbook gets (coordinator and tasks, the
safety boundary and its explicit-request exception, questions to the human,
briefings and the final report, the checks common to every mission), then
each playbook in turn: what it is for, its steps and roles, what the
coordinator does and never does and when the human is asked, what
CodeNomad checks versus what is only an instruction to the model, and what
the mission produces with its typical pitfalls. Every statement was checked
against the recipes and the server checks; decision tags and the
Coordinator decision / Your answer labels are scoped to Native subagents.
"See details" under the playbook description in the editor's Options opens
a read-only view in the Mission reader, beside the editor: steps, roles
with their localized labels, and, folded per recipient, the complete
English texts each agent receives. They come from a new read-only route,
GET /api/missions/playbooks?taskMode=, built by missionPlaybookDetails()
from the real prompt builders (buildAssignmentPrompt, buildActorContext)
with placeholders, so the view cannot drift from what agents get. The
button is disabled while a creation request is in flight and opening the
reader no longer cancels the editor's pending creation. A failed load
offers Retry, and a saved playbook reader is restored, with unknown ids
dropped.
Tests: a drift guard comparing whole sent texts with the export for native
and independent assignments, independent session context, and one-time and
daily coordinators of every playbook, with a negative check and a test
placing each question/safety rule on the right recipients; a route test;
browser tests for See details (including a delayed response) and for
opening it during a creation answered 200 and 400; view-state restoration.
Server, UI unit, mission browser, help structure and help browser tests and
the typechecks pass.
## Summary
- New **Support CodeNomad** help page (10 languages): what sponsorship
pays for, the funding policy (a contribution, not a purchase; never
required to download, use or update) and one button per funding channel
naming who receives the money.
- **Download page** ends with a short *Support development* section with
the same buttons; the help **header** gains a *Sponsor* link; the former
support page is retitled **Bug reports and source builds** (ids
unchanged) so the two are not confused.
- **App**: *Support CodeNomad* in Settings → Info (secondary button
between Updates and Diagnostics), in the Help menu after *CodeNomad
Help* (Electron and Tauri, English help-page fallback) and as a palette
command without a default shortcut. All open the localized help page.
- **Repository**: `.github/FUNDING.yml` lists the maintainer's GitHub
Sponsors profile and the Support page (the Sponsor button needs
*Settings → General → Features → Sponsorships*).
Channels live in `docs/help/funding.json` and render through a
`{{funding}}` directive allowed only on the download and sponsor pages,
so adding a channel needs no retranslation. Entries are validated (exact
keys, unique ids, `https://github.com/sponsors/<login>` only) and
escaped; a page using `{{funding}}` with no channel fails the build. CSP
unchanged.
Agreed with the co-maintainer before publishing.
## Validation
- `npm run test:help`: 31/31 (27 pages × 10 locales, funding validation
and placement).
- `node scripts/test-help-browser.mjs`: 47/47 (header overflow at 390 px
in en/he/ne/ja/zh-Hans, button geometry).
- `npm run typecheck`; unit tests help-url, hotkey-bindings,
menu-labels; browser tests help-command, server-info, view-menu-electron
(22/22); `cargo test` for the Tauri crate (291/291, including the
English sponsor fallback).
- Independent review: zero findings.
## Summary
- New **Download** help page (10 languages): an OS-detecting button
linking straight to the recommended Tauri build, then a static
Tauri/Electron table with every asset and its size, version and publish
date, and the winget/npm commands. The header Download link,
`install.md`, `support.md` and the README point to it.
- New **help home page** (10 languages): cockpit positioning, a
*Download CodeNomad* call to action, a silent 46 s tour that autoplays
on desktop only (poster and YouTube link on narrow screens and with
reduced motion), and short Missions / phone access / long histories
sections before the existing orientation sections.
- **Exact links without network in the builder**: `release:<id>` links
and `{{release}}`, `{{download-button}}`, `{{tour-video}}` directives
resolve from `docs/help/downloads.json` and optional `--release` data;
without data, links fall back to the latest release page.
- **Automatic refresh**: `scripts/resolve-help-release.mjs` (CI only)
picks the newest stable release whose assets are fully uploaded;
`help-pages.yml` republishes after a successful *Release Binaries* push
run on `main`, building trusted `dev` sources with read-only
permissions, the token scoped to the resolver step and one production
concurrency group. Pull requests never resolve or publish.
## Safety
- Release data is revalidated in the builder (exact
`github.com/NeuralNomadsAI/CodeNomad/releases/download/<tag>/<asset>`
URLs, no credentials/query/fragment/traversal, positive sizes, UTC
dates) and escaped.
- CSP stays `default-src 'none'`; only `media-src 'self'` is added. The
download script is allowed on the download page only, the tour video on
the home page only.
## Validation
- `npm run test:help`: 27/27 (26 pages × 10 locales, offline; resolver
selection/pagination, release validation, directive problems, 22
detector cases, workflow gates).
- `npm run build:help` with and without the release fixture.
- `node scripts/test-help-browser.mjs`: 46/46 (download button,
JavaScript disabled, video playback, reduced motion, narrow widths,
RTL).
- Read-only resolver run against the live API resolved `v1.0.0`.
The `workflow_run` path can only be observed on the next stable release
on `main`; `workflow_dispatch` from `dev` exercises resolver → build →
deploy.
AGENTS.md loaded about 33,000 tokens into every agent session, subagent and reviewer, mostly per-feature contracts, and the agent documentation around it had accumulated duplicates, dated logs and history of removed designs. This PR makes AGENTS.md a short set of rules that apply everywhere plus an index of area documents, and leaves AGENTS.md, dev-docs and the repository skills describing only the current state.
Three commits, reviewable separately:
1. **Move (lossless).** Every per-area rule moved verbatim from AGENTS.md into its area document (existing ones, or six new ones: UI_CONVENTIONS, UI_SHELL, COMPOSER, TRANSCRIPT, SETTINGS, PROJECTS). A script split the old file into 208 units, required one destination for each and checked all 199 content units verbatim at their destination. AGENTS.md went from 134,000 to 16,000 characters.
2. **Trim.** A per-area ponytail review removed rules stated two or three times (keeping the more precise copy), dated validation logs, per-version qualification sections below the current minimum, abandoned designs and self-references; seven documents whose surviving rules live elsewhere were deleted. It also fixed statements the code contradicts (locale registration, the Mission play/recovery condition, plugin package updates, cleanup progress UI, timeline index persistence, automation restart/targets, stale pins and minimums).
3. **Current state only.** The new AGENTS.md rule: no history (removed features and their names, former behavior, provenance, dated logs) and no denials; correct a contradicted statement at its source. DEVELOPER_MODE.md is merged into BROWSER_AUTOMATION.md and every Developer Mode mention is gone (including the README and the browser help page in ten locales). Names that only made sense against older designs are renamed with every reference updated, MISSIONS_ENVIRONMENT_ADMISSION is folded into SESSION_ENVIRONMENT, and INDEX lists every document. The server npm README now states the real OpenCode minimum (2.1.2).
AGENTS.md is now about 14,000 characters (roughly 3,500 tokens); AGENTS.md, dev-docs and the vendor README went from about 11,200 lines to under 4,700.
Validation: every relative Markdown link and every cited dev-docs path resolves; no reference to a renamed or deleted document remains; `npm run test:help` passes for all ten locales.
Review: three independent GPT-6.1 Sol (high) reviews by area found binding rules lost in the trim and current-state passes; 25 were restored as present-tense facts or prohibitions and four contradicting statements corrected, each checked against code. A Fable 5.1 gatekeeper review of the whole PR passed; its follow-up routes session recovery from the index, points to dev-docs/INDEX.md and documents the family identity read.
ci(help): remind PRs that change UI labels to update the user help
The help drifted for a week because about forty user-visible PRs merged without touching it, while CI only checks the help's structure and links. The rule asking for help updates in the same PR was buried in the AGENTS.md i18n section; it now has its own short Pull Requests section next to the commit guidelines, which agents consult when committing and opening PRs.
A new non-blocking workflow, help-update-reminder.yml, catches the most common miss: when a PR changes English UI messages (packages/ui/src/lib/i18n/messages/en/) but no file under docs/help/, it posts one marked comment and a warning annotation; once the PR touches the help, the comment is removed. It runs on pull_request_target like the existing Restrict Non-Dev PRs workflow, but only reads the PR file list and comments through the API and never checks out pull request code, so the write-scoped token never runs PR content. Because pull_request_target uses the base branch's workflow, it starts on PRs opened after this merge. USER_HELP.md documents it.
Validation: replayed the filter read-only on past PRs: it would have flagged #1014, #1026 and #1052, which changed labels without updating the help, and stays quiet for #1043 and #1054, which updated it, and for #1057, #1063, #1079 and #1080. The workflow YAML parses, the step passes bash -n, the comment body has no leading indentation and the marker lookup returns the expected comment ID on a real PR. Behavior-only changes without label edits (such as #1063) are not detected; the AGENTS.md rule covers those.
Review follow-up: the reminder only matches comments authored by github-actions[bot], runs are serialized per PR so overlapping events cannot post twice, clearing removes every owned reminder, and the workflow keeps only pull-requests: write.
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.
## 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.