feat(settings): search that finds settings, and takes you to them

[QR-Madness]

Wave 2 of the settings campaign. Wave 1 made every setting declared and documented; this makes them reachable.

The problem

Settings search matched 21 section labels against hand-typed keyword arrays — not the ~200 actual settings. Two consequences:

• Typing the name of a setting found nothing. Searching "verbatim budget" returned no results, because no section is called that.
• The keyword arrays rotted silently. Adding a control never forced anyone to update them, so coverage drifted with every change.

What landed

Search finds settings. Indexed from the manifest, so there's nothing to maintain by hand and a setting is searchable the moment it's declared. Ranking runs exact key → prefix → substring → help text, plus a pass for queries whose words aren't adjacent ("verbatim budget" → context.verbatim_budget_ratio). Secrets and read-only plumbing are excluded — there's nothing to do with them here. Section matching is untouched, so navigating by section still works and sections without manifest coverage are no worse off than before.

Results take you to the control, not to the top of the section containing it. The field kit emits data-setting anchors, and lib/scrollToAnchor.ts generalizes the scroll-and-flash recipe that was inlined in ChatPanel for the Plans drawer. Scrolling without marking leaves you hunting for what changed; the ring says this one. Reduced-motion keeps the mark and drops the movement. The Overview digest lands on controls too; sections not yet manifest-wired degrade to section-level navigation rather than doing nothing.

Deep links work end to end. The modal layer always spread arbitrary props — the chain broke at the settings stub, which destructured onClose alone. Fixed that, gave open() an optional props argument, and pointed ⌘, at the shared surface descriptor instead of a re-declared copy (that duplicate was a drift waiting to happen).

Palette gains Settings: <section> commands, registry-driven exactly like Theme, so a new section is reachable with no edit to the command list. They're searchOnly — ~20 entries would bury the handful worth seeing when the palette opens, so they appear once you've typed.

One real bug, found while verifying

Clearing the focus target as soon as it was delivered re-ran the consumer's effect, and its cleanup cancelled the scroll still in flight — so the flash never landed. The target now carries a sequence number instead of being cleared, which also makes re-selecting the same result flash again.

(Also worth noting: a hooks-order error appeared in the console mid-session. It was an HMR artifact from editing a hook's shape while mounted — reproduced only on hot-reload, and confirmed absent on a clean tab and in a production build.)

Verification

• 1240 backend tests · 474 client tests (20 new: search ranking and filtering, the anchor utility incl. CSS-escaping and late-mounting content, palette gating)
• tsc clean · ruff clean · client lint clean · task docs:check green, zero warnings
• Production build succeeds
• Live on a clean tab, zero console errors: palette deep-link opens Recall directly; "verbatim budget" finds the setting it never used to; hits flash the correct control (memory:recall_ce_max_demotion)
• Mobile (375px): nav takeover renders hits with 48px touch targets

Still out of scope

Migrating the remaining hand-written sections onto the manifest bindings — until a section is wired, its settings are findable but jumps land at section level. That's the Wave 3 help-and-tier cadence, tracked in todo/backlog/genome-advisor.md.

Assisted-by: Opus 5

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agentx-docs-site	Ready	Preview	Aug 7, 2026 12:11am