Skip to content

docs: in-app help, README, CONTRIBUTING and UI strings match current behaviour. Principle VIII. - #6250

Merged
ten9876 merged 9 commits into
mainfrom
docs/stale-help-and-strings
Oct 7, 2026
Merged

ten9876 merged 9 commits into
mainfrom
docs/stale-help-and-strings

Conversation

@ten9876

@ten9876 ten9876 commented Oct 7, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Found while refreshing the GitHub wiki for v26.5.1 → v26.10.1: in-repo text that no longer matches the app. Each item was checked against current source before changing it.

In-app help (resources/help/)

  • aethersdr-help.md: Title Bar section rewritten for the 52 px bar (feat(gui): unified 52 px title bar on Qt 6.12 window chrome — native captions on macOS/Windows, frameless on Linux (RFC #4764) #6198) — radio tabs with the heartbeat on the status dot, ☰ menu, + popover; no heartbeat lamp, lightbulb or Minimal Mode button. Tools → AetherTX… replaces Aetherial Audio; DIGI applet, overlay DSP button and status-bar applet ☰ removed. Default applet order now matches AppletPanel::kDefaultOrder (23 IDs, PHNE).
  • understanding-noise-cancellation.md: BNR runs in-process on a local NVIDIA GPU (no Docker/container, not cloud), with a ~1 GB one-time download matching the Download button (docs/nvidia-bnr.md aligned too); NNR added as the seventh client method; RN2 Noise Floor slider; controls live in Settings → AetherRX… → AetherNR; unavailable methods are dimmed with a reason.
  • configuring-aethersdr-controls.md: a single click on an off-screen indicator activates and recentres (Fix off-screen slice indicator centering #4795).

Docs

  • README: APRS has a station table, not a map; the lightbulb line points to Help → Submit your Idea… 💡; TMate 2, Ulanzi Dial and AetherPad added to Tested Controller Devices.
  • CONTRIBUTING: Help-menu idea route, per-launch logs under <config>/AetherSDR/logs/ (attach the newest; aethersdr.log links to it on Linux/macOS), Help → Support & Diagnostics… / File an Issue….
  • BUILDING: QRhi failure shows the "Spectrum renderer unavailable" card (fix(gui): surface QRhi spectrum failures #4787).
  • psk-reporter-city-lights.md: Warmth default is 0 throughout (kDefaultWarmth).
  • rtty-decoder-implementation.md: the pane opens for RTTY only.
  • DEVELOPER-GUIDE.md: theme tokens instead of hard-coded hex, per AGENTS.md.
  • docs/agents/gui.md: naming examples use the CAT applet (CatControlApplet) and the current Support & Diagnostics log category labels.

UI strings

  • Automation-bridge Access Token tooltip now agrees with docs/automation-bridge.md (export AETHER_MCP_TOKEN only in the launching shell, never in an MCP config). All four bridge tooltips on Radio Setup → Network link the hosted doc rather than a source-tree path.
  • Ulanzi mapper fallback no longer says "Linux build only" (backends exist on all three platforms).
  • File an Issue and Submit your Idea AI prompts fetch AGENTS.md instead of CLAUDE.md.

Packaging

  • 60-hid-encoders.rules: TMate 2 (1721:0614, from kSupportedDevices in HidDeviceParser.cpp), and a note that AetherPad (2341:0266) is deliberately absent because it is the Arduino Giga R1's stock identity.

Testing

  • AetherSDR + 7 related test targets built (lean build, Qt 6.12); radio_setup_label_theme_token_test, radio_setup_recording_mode_dim_test, radio_setup_max_power_field_test, radio_setup_region_field_test, hl2_pc_audio_lock_test, titlebar_headphone_mute_test, automation_menu_lookup_test pass.
  • All Static-checks scripts pass, incl. gen_bridge_docs.py --check; colour ratchet +0; a11y warnings unchanged from base.
  • No test or translation pins any changed string.
  • Not run: the full suite or a live app launch.

🤖 Generated with Claude Code

ten9876 and others added 8 commits October 7, 2026 09:00
… menus. Principle VIII.

AetherSDR Help:
- Title Bar section rewritten for the 52 px bar (#6198): radio tabs whose
  status dot carries the discovery heartbeat, the app-menu button, the
  applet dock icons. No heartbeat lamp, no lightbulb button, no Minimal
  Mode control; Minimal Mode is View -> Minimal Mode / Ctrl+Shift+M.
- Tools -> AetherTX... replaces the retired "Aetherial Audio" item.
- DIGI dropped from the applet list (replaced by the CAT / DAX / TCI / IQ
  tiles, already documented below it).
- Spectrum overlay: the DSP sub-panel is gone; Memory added.
- Status bar: no applet-panel toggle; ASR added.

Understanding Noise Cancellation:
- BNR is the in-process Maxine AFX denoiser on a local NVIDIA RTX/GeForce
  GPU, Linux and Windows; no Docker, no container, not cloud.
- NNR (WDSP neural NR) added as the seventh client method.
- RN2 has a Noise Floor slider (0-50 %, default 0).
- Client NR lives in AetherRX -> AetherNR; the VFO only has the AetherRX
  launcher and the overlay has no DSP panel. Unavailable methods are
  dimmed with a reason, not hidden.

Configuring AetherSDR Controls: a single click on an off-screen slice
indicator activates the slice and recentres it (#4795).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…nd the TMate 2. Principle VIII.

- The title-bar lightbulb is gone (#6198); AI-assisted reports start from
  Help -> Submit your Idea... and Help -> File an Issue....
- Logs are one timestamped aethersdr-YYYYMMDD-HHMMSS.log per launch under
  <config>/AetherSDR/logs/, with aethersdr.log pointing at the newest
  (src/main.cpp, LogManager). "Help -> Support -> Send to Support" no longer
  exists: Support & Diagnostics offers per-module logging and the log
  folder, and File an Issue builds the support bundle.
- The APRS client has a station table, not a station map.
- The ELAD/WoodBoxRadio TMate 2 joins Tested Controller Devices: it has a
  parser, LCD/backlight output and MainWindow overlays (HidDeviceParser,
  HidEncoderManager, MainWindow_Controllers).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…he code. Principle VIII.

- BUILDING.md: a QRhi failure is surfaced. SpectrumWidget handles
  renderFailed (and a missing backend or failed waterfall pipeline) with a
  "Spectrum renderer unavailable" card and a log line (#4787).
- psk-reporter-city-lights.md: Warmth defaults to 0 (CityLightsShading.h
  kDefaultWarmth); the second mention said 25.
- rtty-decoder-implementation.md: refreshRttyDecodeState opens the pane for
  RTTY only, honouring the persisted enable flag (#5353); Auto mark follows
  rttyMark() alone, refreshed on rttyMarkChanged / rttyShiftChanged.
- DEVELOPER-GUIDE.md: Widget Guidelines prescribed hard-coded hex colours,
  against AGENTS.md's ThemeManager-token rule; now states the token rule
  and links the theme and style guides.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…tale advice. Principle VIII.

- Radio Setup -> Network, Access Token tooltip: it told users to paste the
  token into their MCP server config, which docs/automation-bridge.md
  forbids. It now says to export AETHER_MCP_TOKEN only in the shell session
  that launches the assistant, never in an MCP config or shell profile.
- Ulanzi Dial mapper: the null-backend fallback read "Manager unavailable
  (Linux build only)"; Windows and macOS backends exist and are created on
  all three platforms.
- File an Issue (SupportDialog) and Submit your Idea (TitleBar) prompts now
  send the AI to AGENTS.md, the canonical project guide; CLAUDE.md is a
  pointer to it.

No test pins any of these strings.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…VIII.

HidDeviceParser supports the TMate 2 (VID 0x1721, PID 0x0614), but
60-hid-encoders.rules had no rule for it, so a non-root user could not
open its hidraw node. IDs are taken from kSupportedDevices in
src/core/HidDeviceParser.cpp.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
… has them. Principle VIII.

The list named nine applets, used the tray label PHN for the PHNE id and
predated PWR, WFM, WAVE, TXDSP, CAT/DAX/TCI/IQ, PROF, KSDR, HLTH, SS, GHE
and CLOCK. It now mirrors AppletPanel::kDefaultOrder with each applet's
title, notes where the tray button reads differently (PHN, WAV, CLK), and
says that hardware-dependent and default-off applets are not all shown.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…nzi Dial. Principle VIII.

- docs/agents/gui.md: the user-facing-names example cited the retired DIGI
  applet as class CatApplet; the CAT applet's class is CatControlApplet.
- README Tested Controller Devices: AetherPad (Arduino Giga R1 running the
  aether-pad RC-28 emulator, routed to IcomRC28Parser over USB HID as
  2341:0266) and the Ulanzi Dial (Bluetooth HID; evdev on Linux, hidapi on
  Windows, IOKit on macOS; Settings -> Ulanzi Dial Mapping...).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…s shown. Principle VIII.

The naming-convention example pointed at "Help → Support logging" and
category labels that no longer match LogManager's display names.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@ten9876
ten9876 requested review from a team as code owners October 7, 2026 16:27
@github-actions

github-actions Bot commented Oct 7, 2026

Copy link
Copy Markdown

Accessibility check findings

This PR touches src/gui/ files with 9 accessibility issue(s).
Full details appear as inline annotations on the diff above.

Files scanned : 4
Files with findings: 1
Total findings : 9

See docs/a11y.md for the canonical
Qt patterns (setAccessibleName, QAccessibleValueChangeEvent,
QAccessibleInterface subclasses, etc.). Structural remediation
(keyboard navigation, custom QAccessibleInterface subclasses)
is tracked in #3288.

Findings are warnings only — the build is not blocked.

@aethersdr-agent aethersdr-agent Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Issue fit

No linked issue, and none is needed: this is a documentation-accuracy sweep, which GOVERNANCE.md does not route through an RFC. Reviewed against the PR body's own stated intent — "each item was checked against current source before changing it." I treated that as the load-bearing claim and spot-checked roughly two dozen of the individual assertions against the head checkout. Nearly all of them hold, several to the exact constant. No test is required: no behaviour changes, and the three source edits are string-only.

A docs PR's failure mode is a confidently-worded sentence that sends a user somewhere that does not exist, so I prioritised the claims with a reachable wrong answer (paths, defaults, VID/PIDs, enumerated lists) over the prose.

Scope

File(s) What it changes Claimed in body? Verdict
resources/help/aethersdr-help.md Title bar, Tools menu, overlay list, applet order, status bar Yes In scope
resources/help/understanding-noise-cancellation.md BNR/NNR/RN2 rewrite, control locations Yes In scope
resources/help/configuring-aethersdr-controls.md Off-screen indicator click behaviour Yes In scope
README.md, CONTRIBUTING.md Help-menu routes, log paths, controller list Yes In scope
docs/BUILDING.md, docs/DEVELOPER-GUIDE.md, docs/agents/gui.md QRhi card, theme tokens, CAT applet naming Yes In scope
docs/psk-reporter-city-lights.md, docs/rtty-decoder-implementation.md Warmth default, RTTY-only pane Yes In scope
src/gui/{RadioSetupDialog,SupportDialog,TitleBar,UlanziDialMapperDialog}.cpp Tooltip + AI-prompt + fallback strings Yes In scope
packaging/linux/60-hid-encoders.rules TMate 2 udev rule Yes In scope

Everything in the diff is explained by the PR body. No CHANGELOG.md entry was added — correct. The three src/gui edits are string-only; I checked that no control flow, no settings key and no public surface moves with them. No new config key, capability or protocol verb, so no Constitution II/III or AGENTS.md persistence surface is touched.

Blockers

None.

The one candidate I expected to find was the new log path, and it survives. CONTRIBUTING.md sends reporters to ~/.config/AetherSDR/logs/ (and the macOS/Windows equivalents), and LogManager.cpp:323-324 builds exactly that:

    return QStandardPaths::writableLocation(QStandardPaths::GenericConfigLocation)
           + "/AetherSDR/logs/aethersdr.log";

GenericConfigLocation appends no org/app component, so there is no doubled AetherSDR/AetherSDR/ here — all three documented paths are right.

Nits

All non-blocking.

  • resources/help/understanding-noise-cancellation.md:~255 — the BNR download size disagrees with the button it describes. The help text says the Download button "fetches NVIDIA's runtime (about 1.2 GB, once)". That number matches docs/nvidia-bnr.md:60, but the control the reader is looking at says otherwise — src/gui/AetherDspWidget.cpp:1639 sets the button text to "Download (~1 GB)" and :1783 the tooltip to "...(one-time, ~1 GB)". Since this PR's own governing rule is docs/agents/gui.md's "User-facing names match the on-screen labels," the help should probably read ~1 GB and docs/nvidia-bnr.md be reconciled separately.

  • packaging/linux/60-hid-encoders.rules — AetherPad gains a README entry but no udev rule. kSupportedDevices (src/core/HidDeviceParser.cpp:7-24) has seven devices; after this PR the rules file has six. The missing one is the AetherPad at {0x2341, 0x0266}, which this same PR adds to README's Tested Controller Devices as working "over USB HID (hidapi builds)" — on Linux a non-root user cannot open it without a rule. I suspect this was a deliberate omission rather than an oversight, since 0x2341:0x0266 is Arduino's generic composite VID/PID and a blanket MODE="0666" on it would widen access to every stock Arduino Giga on the machine. Worth confirming either way; if it is deliberate, a comment in the rules file saying so would stop the next person filing it as a gap.

  • CONTRIBUTING.md:~34 — the aethersdr.log pointer is a symlink with no platform guard. The new text says "aethersdr.log pointing at the newest" unconditionally. LogManager.cpp:255-257 implements it as QFile::link(candidate, symlink) with the link name dir + "/aethersdr.log". On Windows QFile::link produces a shortcut and wants a .lnk suffix, so the plain aethersdr.log likely never appears there — meaning the Windows half of that sentence may not describe what a Windows reporter actually sees. This is pre-existing product behaviour, not something the PR introduced; the PR only states it. Reasoned from code — I could not run it on Windows. Softening to "the newest file is the one to attach" would be true everywhere.

  • src/gui/RadioSetupDialog.cpp:2009 — repo-relative doc path in an end-user tooltip. The tooltip now ends "See docs/automation-bridge.md.", which means nothing to someone running an installed binary with no source tree. The advice is correct and well-sourced — docs/automation-bridge.md:191-199 says exactly this, including "never in an MCP config file" — so only the pointer needs work; a URL would travel better.

What I tried to break

  • Attacked the body's central claim ("checked against current source") on the most falsifiable items, and it held, repeatedly to the exact value: kDefaultWarmth = 0 (CityLightsShading.h:19); the 23-ID applet list matches AppletPanel::kDefaultOrder (AppletPanel.cpp:167-169) in both membership and order, PHNE included; TMate 2 0x1721:0x0614 matches HidDeviceParser.cpp:24; RN2 Noise Floor 0–50% matches Rn2SettingsModel::kMaxRxDryMix = 0.50f; the AetherNR method strip order (NR2, NR4, MNR, DFNR, RN2, BNR, NNR) matches kLabels at AetherDspWidget.cpp:253; "Six further WDSP tuning controls" is exactly the six in m_nnrAdvanced (:2187-2200).
  • Hunted for an over-deletion in the rewritten lists, and found none. The overlay menu section dropped DSP and added Memory; SpectrumOverlayMenu.cpp:425-433 confirms the live button set is +RX, +TNF, Band, ANT, Display, Memory, DAX — and the help file's unchanged line 163 still carries +RX, so the list is complete rather than quietly truncated. Same check on the status bar: the ASR toggle is real (MainWindow.cpp:5778).
  • Tried to falsify the RTTY "RTTY only" rewrite, which is the change most able to make a doc actively wrong. MainWindow_DigitalModes.cpp:367 gates on isRtty && RttyDecodeSettings::enabled(), and diglOffset no longer appears anywhere in the RTTY decoder or applet sources — so both the RTTY-only scope and the persisted-enable-flag caveat are accurate, and removing the DIGL/diglOffset paragraph was correct rather than a lost feature.
  • Checked the claims that cite a UI affordance existing at all, since those are cheap to assert and easy to get wrong: "Spectrum renderer unavailable" card (SpectrumWidget.cpp:12891), Minimal Mode in View with Ctrl+Shift+M (MainWindow_Menus.cpp:1334), Reset Applet Order (:1311), Tools → AetherTX... (:1461), Help → Submit your Idea... 💡 / File an Issue... (:1699, :1705), the three-missed-beat alarm and right-click blink toggle and EXPERIMENTAL badge (TitleBar.cpp:298-341), NR2's Opus/SmartLink dim reason (AetherDspWidget.cpp:715, #1597) and NR4's Windows-LLVM tooltip (:279). All present.
  • Verified the Ulanzi string change is justified rather than cosmetic. UlanziDialMacOSManager.cpp exists alongside the Windows manager, so dropping "(Linux build only)" from UlanziDialMapperDialog.cpp:254 is a fix, not a preference — the retained comment at :249-250 says "(Linux, Windows)" only about which thread the backend lives on, which is a different statement and still correct.
  • Confirmed the &-mangling in the diff above is a harness artifact, not content. The ${PR_DIFF} fragments in "Support ${PR_DIFF} Diagnostics" and issues?state=open${PR_DIFF}per_page=100 are the task prompt eating &. In the head checkout the files correctly use a single & in prose, while the Qt menu action properly escapes it as "Support && Diagnostics..." (MainWindow_Menus.cpp:1721) — which is also what SupportDialog.cpp:36 titles the dialog. Nothing to fix.
  • Ran the §6 preference check and came up empty. Every edit either corrects text to match shipped code or adds a device already in kSupportedDevices. No default value, keybinding, layout or confirmation changes — the one behavioural-sounding item, the token tooltip, tightens security advice to match an existing doc rather than changing what the code does.
  • Could not verify, and am not reporting as findings: the NNR CPU figures ("~13% of one core", "about twice" for Premium, Raspberry Pi unsuitability) and "runs after the AGC" are measurements and architecture statements with no constant to grep; and I could not locate the mechanism that auto-disables client-side NR on CW/digital, so appending NNR to that pre-existing list is plausible but unconfirmed — VoiceModeGate.h turns out to gate DVK and Copy Assist, not NR. The macOS-only-rebuild caveat in BUILDING.md I also left unchecked. I have no build, no test run and no way to drive the GUI, so every observation above is reasoned from reading the head checkout, not reproduced at runtime.

Recommendation

Approve with nits. This is an unusually well-executed docs sweep — the enumerated lists match the code exactly rather than approximately, which is the part authors normally get wrong, and the three string edits are genuine corrections with citable authority behind each. The four nits are all one-liners and none of them misleads a user into a dead end; the BNR size and the AetherPad udev question are the two worth a reply before merge, and the AetherPad one may just need a confirming "deliberate" so it does not get re-filed later. Thanks for checking each item against source instead of against the old text — it made this reviewable.


🤖 aethersdr-agent · cost: $6.8521 · model: claude-opus-5

@jensenpat jensenpat self-assigned this Oct 7, 2026
jensenpat
jensenpat previously approved these changes Oct 7, 2026

@jensenpat jensenpat left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict

Approve. Docs and three UI strings match current source. No blocker.

Reviewed 3d367fe75d9fd5ae5febd1dd5f4832244a7e273e against origin/main (2a89515d6), which is ahead of the PR base. git merge-tree --write-tree applies cleanly. Required checks on this SHA are green: build, check-macos, check-windows, Static checks.

Issue fit: no linked issue. The body is a Principle VIII sweep so in-repo text matches the app. That is what the diff does.

Scope

Group Files What it does
In-app help resources/help/aethersdr-help.md, understanding-noise-cancellation.md, configuring-aethersdr-controls.md Title bar, menus, 23-ID applet order, overlay Memory, status-bar ASR, client NR (NNR, RN2 Noise Floor, in-process BNR), single-click off-screen recenter
Contributor docs README.md, CONTRIBUTING.md, docs/BUILDING.md, docs/DEVELOPER-GUIDE.md, docs/psk-reporter-city-lights.md, docs/rtty-decoder-implementation.md, docs/agents/gui.md Help-menu route, log dir, controller list, QRhi card, theme tokens, warmth 0, RTTY-only pane, CAT applet and Support category labels
UI copy RadioSetupDialog.cpp, UlanziDialMapperDialog.cpp, SupportDialog.cpp, TitleBar.cpp Token tooltip, Ulanzi fallback, AI prompts fetch AGENTS.md
Packaging packaging/linux/60-hid-encoders.rules TMate 2 1721:0614

No CHANGELOG entry. No default, binding, or protocol change. docs/agents/gui.md is infrastructure CODEOWNERS; the rest is reviewers.

Checked against source

  • AppletPanel::kDefaultOrder is the same 23 IDs in the same order, including WFM and PHNE. Display names and tray abbreviations match makeEntry (PHN, WAV, CLK, Channel Strip, TGXL, PGXL).
  • Overlay buttons are +RX, +TNF, Band, ANT, Display, Memory, DAX. No DSP row.
  • Title bar kHeight is 52. The active tab dot is the discovery heartbeat; three missed beats alarm; right-click toggles blink; EXPERIMENTAL badge is present. Minimal Mode is View / Ctrl+Shift+M. Tools has AetherTX.... Help has Submit your Idea... and File an Issue....
  • Off-screen left-click emits offScreenSliceCenterRequested (activate and center). Right-click opens the slice menu.
  • kDefaultWarmth is 0. RTTY pane is isRtty && RttyDecodeSettings::enabled(); DIGL does not open it.
  • Log categories are Discovery, Connection / Commands, Protocol / Status. Class is CatControlApplet.
  • RN2 dry mix clamps to kMaxRxDryMix 0.50. AetherNR labels are NR2, NR4, MNR, DFNR, RN2, BNR, NNR. NNR Standard/Premium tooltips match the help (~13% of one core, about twice, not for a Pi). The code comment names six undocumented WDSP controls. Client NR disables itself when an audible slice is CW or digital (updateAetherDspModePolicy), NNR included.
  • QRhi failure card title is Spectrum renderer unavailable. macOS text offers only the rebuild; other platforms also offer AETHER_NO_GPU=1.
  • Token wording matches docs/automation-bridge.md (export AETHER_MCP_TOKEN in the launching shell, never an MCP config).
  • TMate 2 {0x1721, 0x0614} is in kSupportedDevices. Ulanzi has macOS and Windows managers, so dropping "Linux build only" is correct.
  • APRS roster is a station table (AprsStationList).

CI on this SHA is the verification for the string and udev edits. I did not rebuild locally; the changes are prose and literals, and Static checks already passed on 3d367fe.

Nits (non-blocking)

  • Help says the BNR Download is "about 1.2 GB", which matches docs/nvidia-bnr.md. The button and tooltip say ~1 GB (AetherDspWidget.cpp). Rounding only; worth aligning later so the help matches the control.
  • CONTRIBUTING.md says aethersdr.log points at the newest file on every platform. LogManager uses QFile::link, which on Windows wants a .lnk shortcut. The timestamped file is the reliable one everywhere.
  • The Access Token tooltip ends with See docs/automation-bridge.md, a repo path an installed app does not have. The advice itself matches the doc.
  • AetherPad (0x2341:0x0266) is in the README and not in the udev rules. That is the right omission: HidDeviceParser.cpp documents it as Arduino's generic composite identity, and a MODE="0666" rule would cover every stock Giga.

Follow-up (not a merge gate)

No new test pins the three changed strings. A small assertion on the token tooltip and the Ulanzi fallback would catch the next stale rewrite. Not required for this PR.

@jensenpat jensenpat removed their assignment Oct 7, 2026
@ten9876 ten9876 self-assigned this Oct 7, 2026

@ten9876 ten9876 left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Issue fit

No linked issue. Reviewed head 3d367fe75d9fd5ae5febd1dd5f4832244a7e273e against the body's stated documentation-accuracy intent and merge base df60f7579bd96a83772d3ad1a57aeec9c43ff4b6. The changes substantially achieve that intent: current menus, applet order, noise-reduction controls, RTTY gating, controller support, and reporting instructions replace stale descriptions. These are accuracy fixes with existing implementation authority, not a new feature or an unapproved UX preference; an RFC is not needed.

Scope

Files/group Change Claimed? Verdict
resources/help/aethersdr-help.md Current title bar, menus, overlay, 23 applet IDs and status bar Yes In scope
resources/help/understanding-noise-cancellation.md Local BNR, NNR, RN2 slider, method availability and current control locations Yes In scope
resources/help/configuring-aethersdr-controls.md Off-screen slice activation/recenter and context menu Yes In scope
README.md, CONTRIBUTING.md APRS table, controller list, Help reporting routes and logs Yes In scope
docs/BUILDING.md, docs/DEVELOPER-GUIDE.md, docs/agents/gui.md Renderer failure notice, theme-token guidance and current names Yes In scope
docs/psk-reporter-city-lights.md, docs/rtty-decoder-implementation.md Warmth default and RTTY-only decoder/mark authority Yes In scope
Four src/gui/*.cpp files Token advice, canonical AGENTS prompt URLs, Ulanzi fallback Yes In scope; strings only
packaging/linux/60-hid-encoders.rules Existing TMate 2's 1721:0614 access rule Yes In scope

Everything in the diff is explained by the body. All eight commits were authored on October 7 and concern the stated sweep. No changed settings key, default, control flow, dependency, radio verb, capability field, architecture baseline or CHANGELOG entry.

Blockers

None.

Nits — explicitly non-blocking

  1. CONTRIBUTING.md:36 — qualify the latest-log pointer claim for Windows. The new cross-platform paragraph promises aethersdr.log pointing at the newest launch. Both the Windows startup branch (src/main.cpp:650) and rotation path (src/core/LogManager.cpp:255) use QFile::link with the name aethersdr.log, rather than a .lnk name. Qt documents that a valid Windows shortcut requires a .lnk extension. The timestamped log is the dependable attachment path across platforms; qualify the pointer as Unix-only or simply direct reporters to the newest timestamped log. This is a documentation overstatement of existing code, not a new product regression. Native Windows behavior was not reproduced.

  2. src/gui/RadioSetupDialog.cpp:2010 — give installed users a usable documentation destination. The updated Access Token tooltip was reproduced through Radio Setup's Network page and correctly says to keep the token out of MCP configs and shell history. Its final See docs/automation-bridge.md. points to a source-tree path an installed application does not provide. Use a hosted documentation URL, such as https://github.com/aethersdr/AetherSDR/blob/main/docs/automation-bridge.md, or omit the pointer. No change to credential handling is needed.

Empirical verification and attacks that held

  • Preflight: no tests added or modified. Inspected all seven targets named in the body before execution. They use socket-free dispatch/state injection; the recording-mode test's demo backend is in-process, with no synthetic firmware peer. All seven passed: six in the restricted environment; radio_setup_recording_mode_dim_test initially timed out after PipeWire/PulseAudio permission errors and then passed in 0.76 seconds with normal local permissions. No claim that the full suite passed; no changed regression test needed mutation checking.

  • Reused the existing lean Qt 6.12 shared-core build from the author's clean checkout, copying the app, core, tests and test registrations into the review scratch directory rather than rebuilding or writing to that checkout. Bridge build metadata stamps e00f790da; git diff e00f790da HEAD contains only docs/agents/gui.md and the udev rule. All compiled application sources, help resources and test sources are identical to reviewed head. This was an execution pass on those existing artifacts, not an independent fresh build.

  • Drove identity pr6250-review on explicit socket /tmp/pr6250-demo-unrestricted/bridge.sock, fresh settings and AETHER_AUTOMATION_NO_TX=1. Connected only DEMO-0001. menu list, invoke, dumpTree, text helpBrowser, slice mode, get slice, and get dsp verified current Help/Settings routes, the updated 52 px/PHNE help resource, seven NR choices, MNR's visible disabled reason, RN2's 0–50 range/default 0, and the new token advice without reading a credential. Settled engine snapshots showed:

    {"sliceMode":"USB","NNR":{"available":true,"enabled":true},"active":"NNR"}
    {"sliceMode":"CW","NNR":{"available":true,"enabled":false},"active":"none"}
    {"sliceMode":"USB","NNR":{"available":true,"enabled":true},"active":"NNR"}

    These are extracted fields from get slice/get dsp, not a single bridge response. Final get radio reported serial=DEMO-0001, panCount=1, sliceCount=1, transmitting=false; closed the review-owned instance. The earlier restricted launch stalled before the bridge started and only that owned process was stopped.

  • Independently checked the 23-ID ordering against AppletPanel::kDefaultOrder, TMate 2 VID/PID against HidDeviceParser, warmth against kDefaultWarmth, RTTY-only gating against refreshRttyDecodeState, single-click handling against the production off-screen event/wiring, the renderer-failure card and platform advice, platform Ulanzi implementations, and AGENTS prompt URLs. No new design, routing, or persistence behavior is hidden in the string edits.

  • All four conformance gate outputs are identical between merge base and head. Colour ratchet: +0 across all three counts. Accessibility: 9 warnings on both sides, unchanged. Bridge-doc generation, test-registration, frozen CI test gate and whitespace checks passed. Automated code-review skill unavailable; verified the previous reviews' leads manually rather than adopting their verdicts.

Hardware convergence, native macOS/Windows GUI behavior, actual BNR download size/denoising quality, and NNR CPU/model-quality estimates were not measured. NNR figures match the existing UI guidance; that is source agreement, not independent performance proof. The demo cannot validate controller hardware or Flex-specific positive effects, and no live radio was contacted.

CI and recommendation

Approve with nits. Required checks are successful on the reviewed SHA, but their pull_request runs were created at 2026-10-07T16:27:40Z. Current main 4b9be492790102ae82070a0bae58795a9e445418 was committed at 2026-10-07T23:01:28Z, so the green checks describe an older merge result, not today's main. The source audit, seven focused test executions and isolated demo verification found no blocker; fix the two copy nits when convenient and leave final approval/merge to the maintainer.

@ten9876 ten9876 removed their assignment Oct 7, 2026
…g, bridge tooltips link the hosted doc. Principle VIII.

- understanding-noise-cancellation.md and docs/nvidia-bnr.md give the BNR
  runtime download as about 1 GB, matching the Download (~1 GB) button.
- CONTRIBUTING.md: attach the newest timestamped log; the aethersdr.log
  link is a Linux/macOS convenience (Windows gets a .lnk shortcut).
- The four automation-bridge tooltips on Radio Setup → Network link the
  hosted docs/automation-bridge.md instead of a source-tree path an
  installed app does not ship.
- 60-hid-encoders.rules says why AetherPad (2341:0266, the Arduino Giga
  R1's stock identity) has no rule.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@ten9876

ten9876 commented Oct 7, 2026

Copy link
Copy Markdown
Collaborator Author

All review nits from @aethersdr-agent, @jensenpat and the maintainer review are addressed in 88e58b0b7:

  1. BNR download size. resources/help/understanding-noise-cancellation.md:255 now says "about 1 GB", matching AetherDspWidget.cpp:1639 Download (~1 GB) and the :1783 tooltip. docs/nvidia-bnr.md:60 is aligned to ~1 GB as well (maintainer call), so every user-facing figure agrees.
  2. aethersdr.log on Windows. CONTRIBUTING.md:35-36 now reads "Attach the newest one; on Linux and macOS aethersdr.log is a link to it." This matches src/main.cpp:650, where the Windows branch uses QFile::link, which produces a .lnk shortcut.
  3. Repo path in the tooltip. RadioSetupDialog.cpp:2010 now links https://github.com/aethersdr/AetherSDR/blob/main/docs/automation-bridge.md. The three sibling tooltips on the same Network page (:2047, :2142, :2220) had the same source-tree pointer and are folded in (maintainer call). strings build/AetherSDR | grep -c blob/main/docs/automation-bridge.md → 4.
  4. AetherPad udev. The omission is deliberate (maintainer call). packaging/linux/60-hid-encoders.rules now says why: 2341:0266 is the Arduino Giga R1's stock identity, so a rule would open every Giga on the machine.

Verification at 88e58b0b7

  • AetherSDR was rebuilt (the RadioSetupDialog.cpp.o objects are newer than the source). radio_setup_label_theme_token_test, radio_setup_recording_mode_dim_test, radio_setup_max_power_field_test, radio_setup_region_field_test and automation_menu_lookup_test all pass (100% tests passed out of 5). No test pins the changed tooltip strings.
  • All 18 static-check scripts plus gen_bridge_docs.py --check exit 0. check_a11y reports the same 9 pre-existing warnings, and git diff --check is clean.
  • All 9 commits report verified=true, reason=valid.

Not done: the suggested string-pinning test for the tooltip and the Ulanzi fallback is not added; it was a non-gating suggestion.

@github-actions

github-actions Bot commented Oct 7, 2026

Copy link
Copy Markdown

Accessibility check findings

This PR touches src/gui/ files with 9 accessibility issue(s).
Full details appear as inline annotations on the diff above.

Files scanned : 4
Files with findings: 1
Total findings : 9

See docs/a11y.md for the canonical
Qt patterns (setAccessibleName, QAccessibleValueChangeEvent,
QAccessibleInterface subclasses, etc.). Structural remediation
(keyboard navigation, custom QAccessibleInterface subclasses)
is tracked in #3288.

Findings are warnings only — the build is not blocked.

@ten9876
ten9876 merged commit 99d1b31 into main Oct 7, 2026
7 checks passed
@ten9876
ten9876 deleted the docs/stale-help-and-strings branch October 7, 2026 23:35
ten9876 added a commit that referenced this pull request Oct 12, 2026
… and re-take the Stable snapshot. Principle VIII. (#6396)

## Summary

This brings the user guide (docs.aethersdr.com) up to date with
everything in v26.10.2 and re-takes the Stable snapshot so the default
site shows it. Docs only, apart from the TCI page prose in
`tools/docs/gen_reference.py`; no application source, test or CI
changes.

Every page was audited against the 106 PRs in the release. Every fact
that was added or kept was checked against the source at `f753dbfc4`,
the v26.10.2 release commit, not taken from the PR bodies alone.

## What changed

- **Menu paths.**
- AetherModem, Callsign Lookup, AetherMap and FreeDV Reporter are on
**Tools**. They are created on View and then moved to Tools
(`MainWindow_Menus.cpp:1519-1520`, `:1569-1575`); the style guide's
example says **Tools → AetherMap...**.
  - **Show live CW contacts** is on **View**.
  - Waveforms is on **Tools**, not File.
  - The VUDU applet button was called TXDSP.
  - Labels now match the source's `...` vs `…`.
- **Gaps from this cycle.**
- **Windows and Network Diagnostics:** Windows Firewall rules and the
Network Diagnostics Windows Firewall page (#6289); the `aether.network`
and `aether.nvafx` log categories (#6289, #6308).
  - **Remote access:** Tailscale shim revocation semantics (#6325).
  - **Sleep, App Nap and power throttling (#6195):** per-OS notes.
- **Hermes-Lite 2:** state restore, RX audio at unity, CW at TUNE level,
multi-interface discovery and a discovery troubleshooting entry (#6259,
#6254, #5975, #6009, #6293).
- **ANAN-G2:** AGC-T range, a "What is remembered" section, and supply
voltage and link status (#6282, #6129, #6137, #6211).
  - **NB2** on the HL2 and ANAN-G2 (#5966).
- **DVK:** WAV import requirements, the slot menu without Delete, status
text and licensing (#6247, #6262, #6251).
  - **Copy Assist** from unprocessed audio (#6216).
  - **Live CW contacts** replace the decoder's contact card (#6268).
  - **Status-bar indicators** work from the keyboard (#6267).
- **Volume:** controllers, hotkeys and TCI `volume` follow the active
output (#6129, #6260).
- **Peripherals:** the KPA1500 (#5905), CTR2 link extensions and the
AetherKnob (#6338), TMate 2 udev (#6250), MIDI RADE Modem and FDV modes
(#6031, #6038).
  - **RTL-SDR:** live PPM (#6082).
  - **Icom:** COMP and the MK2 squelch scale (#6174, #6184).
- **Known issues.** Entries whose GitHub issues are closed are removed
(each checked with `gh issue view`). As decided, this includes three
closed today without a demonstrated fix: #5107, #4824 and #5665.
- **US spelling.** `docs-style-guide.md` asked for British spelling; it
now asks for US, by the maintainer's decision, and every page is
converted. The generated TCI pages are converted at their source, the
prose strings in `tools/docs/gen_reference.py`. Code spans, links and
URLs were left alone. UI labels were checked against the source strings,
and none of them are British. Two in-page anchors and two Log Analyzer
rule anchors (`#bnr-is-grayed-out-…`) follow the renamed headings.
- **Stable snapshot.** `snapshot_stable.py 26.10.2` was re-run on the
release tree with these corrections, before `main` was merged in, so
Stable carries no post-release docs. `docs/` also has `main`'s
post-release pages, in US spelling. Stable alone keeps the IC-9700
waterfall-rate entry (#5996): #6402 fixed it after the 26.10.2 tag, so
26.10.2 still has it. The PDF manual already attached to the v26.10.2
release keeps the tag's docs.

## Validation

- `npm ci && npm run build` in `docs/user`: success. This is the
broken-link and broken-anchor check.
- `node tools/docs/test_log_rules.mjs`: 707 checks passed for 45 rules.
- `python3 tools/docs/gen_reference.py --check`: up to date (8 pages).
- `git diff --check`: clean.
- Menu paths on a build of this branch (offscreen, isolated settings, no
radio), `menu list`: `Tools → AetherModem...`, `Tools → Callsign
Lookup...`, `Tools → AetherMap...`, `Tools → FreeDV Reporter...`, `Tools
→ Waveforms...`, `View → Show live CW contacts`.

## Screenshots now out of date (not recaptured)

These need a recapture pass on the radio:
- **Old panadapter title strip (#6386):** `panadapter`, `main-window`,
`first-session-*`, `multi-slice-two-slices`, `split-pair`,
`tnf-markers`, `offscreen-vfo-indicator`, `pan-3d-stacked-trace`,
`default-light-theme`.
- **Pre-canon windows (#6334, #6339, #6341, #6372):** `aetherrx*`,
`aethertx*`, `aethermodem-aprs`, `bnr-panel`, `connect-dialog`,
`connect-by-ip-card`, `connect-icom-rows`, `connect-smartlink-card`,
`rx-agc-calibration`.
- **Other:**
  - `title-bar` (lowercase tab states, #6281);
  - `menu-help` (#6294);
  - `display-panel` (#6371);
  - `support-diagnostics-dialog`;
  - `waveforms-dialog` and `tailnet-remote-access` (show shim 0.4.0);
  - `about-window` (v26.10.1);
  - `radio-setup-qrz`.

## Found during the audit, not fixed here

- **App string bug:** `TailnetShimDialog.cpp:628` tells the user to
"Connect remotely with Connect → Manual"; the real path is **File →
Connect to Radio... → Connect by IP**.
- **ANAN AGC-T tooltips:** the RX applet and VFO tooltips show the
slider position as dB, which is wrong on ANAN. #6282 lists this as a
follow-up.
- **MIDI Master Volume on non-Flex radios:** it is refused while PC
Audio is off, whereas hotkeys, FlexControl and HID drive the line out.
The docs describe the code as it is.
- **RTL mode names:** `rtl-sdr.md` writes "FM-N" and "CW-R", but the
source strings are `FMN` and `CWR`. Left as is until someone confirms
what the mode menu displays.
- **IC-705 COMP readback:** inferred from the MK2 (#6174) and not
verified on an IC-705.
- **Not yet documented:** the #6230 Radio Health row "Forward responses
skipped", and the Store/MSIX package.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants