docs(automation-bridge): full verb audit — document every bridge verb (#3928) by jensenpat · Pull Request #3929 · aethersdr/AetherSDR

jensenpat · 2026-06-30T22:25:16Z

What

Issue #3928 asked to document the four verbs PR #3920 added to the header but not to the public reference. This goes further per the request: a full audit of every automation-bridge verb, so docs/automation-bridge.md is a complete, categorized reference an agent can drive from. The audit found the doc was missing far more than four — ~20 verbs and several sub-actions had no public documentation.

Audit method

Extracted the complete verb surface from the code (the handleLine dispatch, every doInvoke action, every doGet model, and all do* sub-action handlers), cross-checked it against the doc, and verified completeness against the raw cmd == / model == / action == token lists. Result: every cmd token, get model, and invoke action is now documented (self-checked — zero missing).

What was undocumented (now fixed)

Area	Was missing
New sections	`window`, `resize`, `menu`, `tune`, `slice` (full: add/remove/select/tx/txant/rxant/rxsource), `txwaterfall`, `floors`, `whoami`, `mark`, `log`, `record`, `station`
Transmit (gated) group	`key`, `cwx`, `txtest`, `atu`, `testtone` — with the `AETHER_AUTOMATION_ALLOW_TX` rail + force-unkey watchdog spelled out
`invoke` actions	`selectRow`, `submit` (+ submit-vs-setText)
`get` models	`dsp` (corrected `active`/`methods`/`tuning` shape — no top-level `enabled`), `meters`; noted `receiveSync` aliases `sync`
`streams`	`resync` (alias `refresh`); ~500 ms re-poll framed as best-effort, not a contract
`dumpTree` node fields	`windowState`, checkable-button `text`/`checked`, `sliceId`, per-node `noiseFloorDbm`/`displayFloorDbm`
TX-safety callout	corrected the button name-fallback to the narrowed `mox/ptt/transmit/cwx` set (`tune`/`atu`/`vox` were dropped in #3918 so "Tune Now" isn't false-blocked)

Plus a new Verb index at the top of ## Verbs: one categorized quick-reference table of the complete catalog, each row linking to its section.

Proof — spot-checked live

Docs-only (no code change), but every documented request/response shape was run against a live bridge (QT_QPA_PLATFORM=offscreen, FLEX-8400M) and the JSON matched, e.g.:

get dsp active      → {"model":"dsp","ok":true,"property":"active","value":"none"}
window fullscreen   → {"action":"fullscreen","ok":true,"windowState":"fullscreen", …}
streams resync      → {"ok":true,"scope":"radio","resync":"requested","hint":"re-poll 'streams radio' after ~500ms …"}
log set aether.dsp on → {"enabled":true,"id":"aether.dsp","ok":true}
floors              → {"ok":true,"floors":[{"panIndex":0,"noiseFloorDbm":-99.68,"displayFloorDbm":-99.17,"visible":true}]}
invoke … selectRow 0 → {"ok":true,"selectedRow":0,"selectedRowText":"✓", …}

Fixes #3928.

💻 Generated with Claude Code (Opus 4.8) with architecture by @jensenpat

aethersdr-agent · 2026-06-30T22:31:58Z

Hi @jensenpat — thanks for the thorough verb audit here, this is genuinely useful reference work. 🙏

I looked into the failing check and I'm confident this is a CI-infrastructure failure, not a problem with your change.

Why I'm confident

This PR modifies exactly one file — docs/automation-bridge.md (448 additions, 9 deletions, no source files touched). A documentation-only diff cannot cause a C++ compilation failure.
The job that failed is check-macos, and it failed in the Build step (run 28479828370). All the earlier steps — Homebrew deps, DeepFilterNet3 setup, ccache, Configure, Opus/RADE — passed, then the compile step itself fell over.
At the time I checked, the Linux build and check-windows jobs were still in progress (not failed). A real source defect would fail the compile on every platform, not just macOS.

Put together — docs-only diff + macOS-only failure in the compile step — this is almost certainly a transient on the macOS runner (an interrupted/poisoned ccache entry, a Homebrew/toolchain hiccup, or the runner running out of resources mid-compile), not anything in your text.

A caveat on transparency: the log tooling I have surfaces step-level pass/fail but not the raw compiler output for this run, so I can't quote the exact error line — I'm deliberately not inventing one. The diagnosis above is from the changed-file list and the job topology, both of which are unambiguous.

Suggested fix

Just re-run the failed check-macos job — a maintainer can hit Re-run failed jobs on the run page, or push an empty commit (git commit --allow-empty -m "ci: re-trigger") to kick a fresh build. No code change is warranted. If a clean re-run still fails the macOS compile on a docs-only branch, that's a CI config issue on main worth a separate look (and would affect every open PR, not just this one).

No Copilot or other reviewer comments are present on this PR, so there's nothing code-related to fold in here.

Thanks again for taking the time on this — it's a docs win and the failure isn't on you. 👍

_{🤖 aethersdr-agent · cost: $3.1847 · model: claude-opus-4-8}

@jensenpat

…aethersdr#3928) PR aethersdr#3920 added four verbs to the header comments but never to the public reference. A full audit of AutomationServer.{cpp,h} against docs/automation-bridge.md found the doc was missing far more than those four: ~20 verbs and several sub-actions had no public documentation at all. Audit method: extracted the complete verb surface from every handler (handleLine dispatch, doInvoke actions, doGet models, and all do* sub-action handlers), cross-checked it against the doc, and verified completeness against the raw `cmd ==`/`model ==`/`action ==` token lists. Every cmd token, get model, and invoke action is now documented (self-checked). Added/updated: - New "Verb index" — one categorized quick-reference table of the complete catalog, each row linking to its section. - New sections: window, resize, menu, tune, slice (full: add/remove/select/tx/ txant/rxant/rxsource), txwaterfall, floors, whoami, mark, log, record, station, and a "Transmit verbs (gated)" group (key, cwx, txtest, atu, testtone) with the ALLOW_TX rail + force-unkey watchdog spelled out. - invoke: documented selectRow and submit (and submit-vs-setText). - get: added dsp (with the corrected active/methods/tuning shape) and meters; noted receiveSync is an alias of sync. - streams: added resync (alias refresh); framed the ~500ms re-poll as best-effort. - dumpTree: documented windowState, checkable-button text/checked, sliceId, and the per-node noiseFloorDbm/displayFloorDbm. - TX-safety callout: corrected the button name-fallback to the narrowed mox/ptt/transmit/cwx set (tune/atu/vox were dropped in aethersdr#3918). Docs-only; no code change. Every documented request/response shape was spot-checked live against a running bridge (offscreen, FLEX-8400M). Fixes aethersdr#3928. 💻 Generated with Claude Code (Opus 4.8) with architecture by @jensenpat Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

aethersdr-agent

Thanks for this, @jensenpat — this is an unusually thorough docs PR, and the "full audit" framing holds up under verification.

I cross-checked the doc against src/core/AutomationServer.cpp rather than taking the audit on faith, and the high-risk factual claims are all accurate:

Complete verb coverage — every cmd == token in handleLine (33 of them: ping/dumpTree/grab/floors/whoami/invoke/close/drag+mouse/showMenu+openMenu/contextMenu/menu/resize/window/get/connect/disconnect/tune/slice/pan/streams/txwaterfall/log/mark/audioCapture/record/station/key/cwx/txtest/atu/testtone) appears in the new Verb index. No misses.
TX-safety fallback list — the narrowed mox/ptt/transmit/cwx set and the "tune/atu/vox dropped in #3918" rationale match isTransmitControl/isTransmitAction (AutomationServer.cpp:859-895) and the explanatory comment verbatim.
get dsp shape — dspEngineSnapshot returns exactly active/methods/tuning with no top-level enabled (lines 1264-1266), and methods.<NAME> carries available. The doc's correction is right.
invoke selectRow/submit — the side-effect-free setText vs returnPressed-firing submit, and the selectedRow/selectedRowText echo, match lines 2431-2504.
streams resync (alias refresh), the windowState enum, and the ~500ms best-effort hint all match the implementation.

No code changes, scope is confined to the single doc file, and CI is green. The #transmit-verbs--gated anchor's double hyphen is correct for GitHub's emoji-stripping anchor generation, so the index links resolve.

Nothing blocking from me — this materially improves the reference. Nice work.

_{🤖 aethersdr-agent · cost: $4.6001 · model: claude-opus-4-8}

ten9876

Approved. Accuracy + completeness review (docs cross-checked against the AutomationServer implementation):

Completeness ✅ — all 33 dispatch verbs are now documented (diffed the ### headings against the verb dispatch). Closes #3928.

Accuracy ✅ — verified against the code: the TX-safety gating (key/cwx/txtest/atu, AETHER_AUTOMATION_ALLOW_TX, the watchdog, unkey-always-allowed, force-unkey-on-stop), plus invoke actions (incl. selectRow), the get model list, window states, streams sub-actions, and dumpTree/grab/resize all match.

Minor (non-blocking) nit worth a follow-up tweak: the "Transmit verbs (gated)" section header implies every verb in it keys TX and needs ALLOW_TX, but testtone (in that section) is ungated and never keys — the section's own testtone subsection correctly says so, so it's an internal contradiction. Safe direction; consider scoping the header to the gated verbs or moving testtone to a non-gated note. resize's empty-value default and the streams empty/default action could also be spelled out more explicitly.

#3961) ## Release documentation prep for **v26.7.1** (2026-07-02) 29 commits since v26.6.5. Docs-only + version bump — no code behavior change. ### Version bump 26.6.5 → 26.7.1 The three canonical locations (per `AGENTS.md`): - `CMakeLists.txt:2` — `project(AetherSDR VERSION 26.7.1)` → `AETHERSDR_VERSION` (the app's version string) - `README.md` — Current version line - `AGENTS.md` — Current version line ### `CHANGELOG.md` Promoted `[Unreleased]` → **`## [v26.7.1] — 2026-07-02`** in house style (v-prefix, em-dash, "N commits since…" opener + headline), authored from all merged PRs and categorized: - **Added:** 3D stacked-trace spectrum (#3899), 3D dBm scale (#3937), in-process NVIDIA BNR + AFX download-on-demand (#3902), TX meter mouse-over readouts (#3936), SWR manual sweep range (#3885), CW sidetone capture (#3895), KiwiSDR metadata scaffolding (#3898), bridge verbs (#3920) - **Changed:** BNR container/NIM backend removed, 60 fps + per-pixel GPU FFT trace (#3958), FlexLib-sourced model capabilities (#3954/#2177), RX speaker-latency cut (#3897), Display pane sections (#3935) - **Fixed:** #3922, #3926, #3941, #3940, #3942, #3921, #3903, #3892, #3924, #3891, #3890, #3900, #3947 - Fresh empty `[Unreleased]` restored above the release block. Internal/CI/docs/self-fix PRs (#3931/#3916/#3934/#3929) omitted per house style. ### `ROADMAP.md` - Cycle header → "post-v26.7.1" - NVIDIA BNR removed from **In flight** (shipped this cycle) - Five v26.7.1 highlights prepended to **Recently shipped** ### `README.md` - Highlights: GPU spectrum bullet now notes the **per-pixel FFT trace at up to 60 fps** and the **3D stacked-trace** spectrum mode ### Reviewer notes - Touches protected paths (`*.md` + `AGENTS.md` Tier-1 + `CMakeLists.txt`) — needs `@aethersdr/infrastructure` sign-off. - Tagging `v26.7.1` and cutting the release build are **not** part of this PR (docs prep only). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

jensenpat marked this pull request as ready for review June 30, 2026 23:26

jensenpat requested a review from a team as a code owner June 30, 2026 23:26

jensenpat force-pushed the fix/3928-bridge-verb-docs branch from e94d10c to a2813f1 Compare June 30, 2026 23:31

aethersdr-agent Bot reviewed Jun 30, 2026

View reviewed changes

ten9876 approved these changes Jul 1, 2026

View reviewed changes

ten9876 merged commit f43ab54 into aethersdr:main Jul 1, 2026
4 checks passed

ten9876 mentioned this pull request Jul 2, 2026

docs(release): prep v26.7.1 — version bump, CHANGELOG, ROADMAP, README #3961

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(automation-bridge): full verb audit — document every bridge verb (#3928)#3929

docs(automation-bridge): full verb audit — document every bridge verb (#3928)#3929
ten9876 merged 1 commit into
aethersdr:mainfrom
jensenpat:fix/3928-bridge-verb-docs

jensenpat commented Jun 30, 2026

Uh oh!

aethersdr-agent Bot commented Jun 30, 2026

Uh oh!

aethersdr-agent Bot left a comment

Uh oh!

ten9876 left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

jensenpat commented Jun 30, 2026

What

Audit method

What was undocumented (now fixed)

Proof — spot-checked live

Uh oh!

aethersdr-agent Bot commented Jun 30, 2026

Why I'm confident

Suggested fix

Uh oh!

aethersdr-agent Bot left a comment

Choose a reason for hiding this comment

Uh oh!

ten9876 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants