feat(page): server-rendered docs search + ⌘K palette, inside docs-nav

[mhenrixon]

Closes #19.

Every docs-kit site now gets search from the gem — no external service, no build step, no JavaScript required, and no second Stimulus controller. It's shaped by Critical Rules 3 & 4: the server renders a working page; the one docs-nav controller only enhances it.

How it works

The index is built structurally from the pages themselves: each authored registry page is rendered to its Markdown twin (DocsKit::MarkdownExport) and split on its ## headings into searchable sections — the same twins llms-full.txt serves, so search can never drift from what a page says. There's no hand-maintained second registry (the drift-prone thing app-4 kept).

The section anchor the twin drops is recomputed as heading.parameterize — exactly the slug DocsUI::Section stamps on its <section id> — so a result links straight to the section. Verified in the dogfood: a result href="/docs/authoring#one-command" resolves to a real <section id="one-command">.

Scoring is plain Ruby: title > heading > body, all query words must match (AND), capped at 20, each hit carrying an HTML-safe snippet (the term wrapped in <mark>, everything else escaped).

JS off → works. JS on → palette.

• JS off: the topbar box is a plain GET form to c.search_path. Enter lands on a fully server-rendered results page (DocsUI::SearchResults) through the chrome, results grouped by page, each linking to its section anchor.
• JS on: the one docs-nav controller upgrades the box into a command palette — / or ⌘K/Ctrl+K focuses it, keystrokes fetch search.json (debounced) and fill a server-rendered dropdown, arrow keys + Enter navigate. If the fetch ever fails, Enter still submits the form to the results page — never a dead end.

Config

Both optional; the defaults just work:

DocsKit.configure do |c|
  c.search      = true           # default; false hides the box site-wide
  c.search_path = "/docs/search" # default; match your route if you move it
end

The install generator draws the route above docs/:doc (or it would swallow /docs/search as :doc); docs-kit new inherits it. The JS-only palette classes (menu-title/menu-active) are forced via @source inline, the same way the Drawer classes are — bin/build-css scans the gems' .rb, not their .js.

New surface

File	Role
DocsKit::SearchIndex (+ SearchIndex::Snippet, DocsKit::SearchHit)	Pure-Ruby index + scorer, no Rails
DocsKit::SearchController	html + json, same shape as LlmsController (gem controller, host-drawn route)
DocsUI::SearchBox	Topbar form + palette markup (rendered when search_enabled?)
DocsUI::SearchResults	The JS-off results page body

Test plan

• search_index_spec — per-section entries, recomputed anchors, title>heading>body ranking, multi-token AND, cap-20, HTML-escaped + <mark>-highlighted snippet, empty-twin, blank/no-match
• search_results_spec — grouping by page, anchored hrefs, zero-hit guidance, q param escaping
• search_box_spec / shell_spec — real GET form to search_path, docs-nav targets/actions, hidden palette, absent when c.search = false
• search_controller_spec — source wiring (ActionController::Base, protect_from_forgery, html+json, no #config shadow)
• install_generator_spec — route drawn, idempotent, ordered above docs/:doc

Verification

• bundle exec rake — 377 examples, 0 failures, rubocop clean, 95.83% line coverage
• cd docs && bun run build:css — menu-title/menu-active/dropdown-content/input all present, nothing tree-shaken
• Dogfooded /docs/search (html and json) end-to-end against the docs app: full chrome, grouped anchored results, <mark> highlights, blank→prompt, no-match→guidance
• JS-off result anchors resolve to real <section id>; /docs/search does not shadow /docs/:doc (both 200)
• Backwards compatible — new knobs default on with sensible values; existing sites re-run the generator (or paste one route line)