Skip to content

feat(settings): Move the BYO Harness architecture copy behind disclosures - #870

Merged
omesser merged 1 commit into
mainfrom
feat/548-settings-disclosure
Sep 22, 2026
Merged

omesser merged 1 commit into
mainfrom
feat/548-settings-disclosure

Conversation

@omesser

@omesser omesser commented Sep 21, 2026 •

Copy link
Copy Markdown
Owner

Why

#548 asks for everyday Settings screens that scan without reading architecture paragraphs. #593 built the mechanism — FormRow and FormSection carry disclosure and status, and all four renderers (AppKit, GTK, Win32, webview) draw them — and moved 22 rows and sections behind it. The one section added since, the "Harness you run yourself" MCP registration block from #599, landed with no disclosure at all, so its 196-character section comment and a 155-character row help sit in the default view of the AI tab, next to helps that run 38–62 characters.

What changed

Two moves in byo_section() in src-tauri/src/settings/form.rs, and nothing else. Both fixtures regenerated to match.

Where Stays in the default view Moved behind the disclosure Why it earned it
Section comment "For a Harness you start in your own terminal." "Registering ai-buddy as an MCP server there lets it speak, move and emote the buddy on your screen. Nothing here changes which mind the Director uses." The first sentence tells a scanning user whether the section is for them. The rest is mechanism (what an MCP server registration does) and scoping against the Director, which is architecture — a user pasting the snippet does not need either.
Registration snippet help "Good for this app run only. Come back here and copy it again after a relaunch." "The port and the token are both new every launch, so a paste from yesterday stops connecting." What the user needs is the rule (per-run, recopy). Why the rule holds — port and token rotation — is mechanism. This is the marginal one of the two; it was 2.5× the length of every other help on the tab.

Deliberately left alone, after auditing every section comment, row help and label in the form:

  • Everything that already has a disclosure from feat(settings): Progressive disclosure data structures for everyday Settings #593. Nothing there is architecture in the default view.
  • The remaining BYO helps ("Paste at Hermes auth prompt; no Bearer prefix; rotates each launch." and "This token reaches ai-buddy and nothing else. The Harness signs itself in.") — short, and every clause is something the user acts on.
  • The Privacy section comment ("Checking a box asks macOS for the permission…") and the Model API preset help ("Fills in the Base URL below…") — practical instructions, not architecture, and under 105 characters.
  • The Development tab. Its "Working directory" help repeats a sentence from the section disclosure verbatim, but that tab is for developers who know the system, and the issue keeps it unchanged.
  • Director vocabulary ("Director" is our word, not the user's — and it names the Completer's settings #466) — the word moves into a disclosure unchanged.
  • No renderer was touched. Section comments with a disclosure and InspectBlock rows with a disclosure both already exist elsewhere in the form, so all four surfaces already draw this shape.

How to verify

  • cargo test -p ai-buddy — 529 passed, 0 failed, 6 ignored. both_ai_sources_serialize_to_the_committed_fixtures passes against the regenerated fixtures, and each fixture diff contains only the two moves above.
  • node --test tests/*.test.js — 288 passed, 0 failed.
  • cargo clippy --workspace --all-targets -- -D warnings — clean.
  • pre-commit run --all-files — every hook passed.

On a build, open Settings → AI and scroll to the "Harness you run yourself" section: one-line section comment, the disclosure below it, and a one-line help under the registration snippet.

Notes

Closing #548 rather than referencing it. Its three acceptance boxes: scannable everyday screens (this PR, on top of #593 — every everyday section comment is now at most 105 characters and every everyday help at most 85, with a disclosure wherever there is mechanism to explain); Development tab unchanged on the main strip (untouched); specified enough for GTK / AppKit / Win32 parity (the copy lives in the shared FormDescription, so the three native renderers and the webview cannot disagree). The optional dated Settings IA page the issue floated is skipped, as the issue marks it optional.

Refs #548

— Claude Code agent, on @omesser's behalf.

🤖 Generated with Claude Code

On closing

Left as Refs. The first acceptance box, "everyday Settings screens are scannable without reading architecture paragraphs", is a judgment about the product rather than a check a diff can settle, and the issue still carries needs-triage. The issue's optional second proposal, a dated Settings IA page, is also untouched. Closing it is the owner's call to make with a look at the screens, not this PR's to take on merge.

…ures

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@omesser
omesser merged commit b3a5c97 into main Sep 22, 2026
5 checks passed
@omesser
omesser deleted the feat/548-settings-disclosure branch September 22, 2026 00:04
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.

1 participant