Add a Meilisearch provider layer

[TitusKirch]

Before you start

• I searched existing issues and didn't find a duplicate

What problem are you trying to solve?

duxt will expose normalized, build-time search records through #16. A site that already runs Meilisearch needs an official way to consume those records without recreating duxt's source, version, locale, and generated-section logic.

The built-in search decision in #33 must remain independent: Meilisearch is an opt-in provider for consumers that choose to operate or buy the service.

Proposed solution

Provide a Meilisearch provider layer that consumes duxt:search:records after #16 lands.

It should let a consumer synchronize the complete current record set to a Meilisearch index during its build, with stable record identity and removal of records no longer present in a later build. Searchable content and filterable provenance must preserve the common contract: URL, title, normalized plaintext, source, version, and locale.

The provider layer owns its credentials, service configuration, synchronization policy, and browser search integration. duxt itself gains no Meilisearch SDK, runtime hook, or service dependency.

Alternatives considered

• Make Meilisearch the duxt default: rejected because every consumer would have to operate or pay for an external service.
• Build a separate crawler or scraper: rejected because Decide the extension surface: hooks, plugins, or neither #16 already provides the normalized records.
• Include the adapter in Evaluate one search index across all sources #33: rejected because Evaluate one search index across all sources #33 decides only the built-in Pagefind default.

Additional context

• Depends on Decide the extension surface: hooks, plugins, or neither #16 landing duxt:search:records.
• Evaluate one search index across all sources #33 evaluates Pagefind as the built-in consumer of the same records.
• The provider must work for records from every source, version, locale, and generated section.

Decided (refinement pass, 2026-09-11):

• The official provider ships as the independently published companion Nuxt layer @kirchdev/duxt-meilisearch, in its own repository. It consumes the public hook but is not a workspace package or optional export of @kirchdev/duxt.
• Add a Meilisearch provider layer #75 remains blocked by Decide the extension surface: hooks, plugins, or neither #16. Implementation begins only once duxt:search:records has landed; GitHub records this as a native “blocked by Decide the extension surface: hooks, plugins, or neither #16” dependency.
• @kirchdev/duxt remains free of the Meilisearch SDK, credentials, runtime hooks, and service configuration. Those are exclusively the companion layer’s responsibility.
• Only an explicitly enabled production sync may modify Meilisearch. Local development, previews and pull-request builds must never alter a production index. The write key is a server-side build secret.
• Synchronization is atomic. The provider builds the complete current record set in a staging index, waits for all indexing tasks, then atomically swaps it with the configured production index. It cleans up the old staging index only after a successful swap.
• Browser integration is opt-in and uses a least-privilege public configuration. The provider exposes only the Meilisearch host, index name and an index-scoped search key to the browser; its private build key remains server-side. Browser results retain duxt’s URL, title, normalized content and provenance model.

[TitusKirch]

Blocked — the deliverable this issue decides cannot be produced by a run inside kirchDev/duxt.

Not a code problem and not an ambiguity in the requirements: the requirements are clear, and they place the artifact outside this repository.

The two sides

What the issue decides (refinement pass, 2026-09-11, body):

The official provider ships as the independently published companion Nuxt layer @kirchdev/duxt-meilisearch, in its own repository. It consumes the public hook but is not a workspace package or optional export of @kirchdev/duxt.

#16's own decided list says the same thing from the other end — "A provider layer owns its credentials, synchronization policy, and browser integration. duxt ships no provider SDK" — and the surface that landed in 059cd6a is written to match: search-records.ts and docs/4.reference/12.hooks.md both illustrate the seam as extends: ['@kirchdev/duxt', 'duxt-typesense'], an unscoped sibling package.

What this loop can reach. The implement loop is configured work.branch = "branch:dev" and gates on pnpm check in a worktree of this repository. Every shape that would land the layer here is excluded by name in the body above:

Shape	Why not
packages/duxt-meilisearch/ in pnpm-workspace.yaml	"not a workspace package"
A root module plus @kirchdev/duxt/meilisearch in exports	"not an optional export of @kirchdev/duxt"
The meilisearch SDK in this package.json	"duxt itself gains no Meilisearch SDK … or service dependency"

kirchDev/duxt-meilisearch does not exist. Creating it is not something this loop should do unattended: it claims a new public repository and the npm name @kirchdev/duxt-meilisearch, and per CLAUDE.md an open-source repo here also carries an OpenTofu-provisioned Discord forum, workflow stubs calling kirchDev/workflows, release-please with a publish job, and a deploy identity — none of which a worker in this repository can provision, and none of which pnpm check here would ever gate. kirchDev/duxt-starter is the precedent: a companion repo created and scaffolded deliberately, not emitted by a drain.

So a guessed merge here would either contradict a decision made today or leave a half-scaffolded public repository behind. Reporting the contradiction is the correct outcome.

What would unblock it

Either of these, and the work is straightforward from there:

1. Create kirchDev/duxt-meilisearch with the usual kirchDev scaffolding and run the implement loop against that repository. This issue then becomes a tracking issue, or moves there.
2. Revise the decision so the provider may live in this repository after all — as a workspace package under packages/, or as a second published package. That is a one-line body edit, and it makes the issue implementable here as written.

A third, smaller option if neither is wanted yet: narrow this issue to the in-repo half only — a docs/3.guides/ page showing a consumer how to write the Meilisearch listener against duxt:search:records (the shape docs/3.guides/9.send-analytics-events.md already uses for an opt-in third-party integration, where duxt ships the seam and the guide ships the wiring). That contradicts nothing, but it is not "a provider layer", so it needs to be said rather than assumed.

#74 (Typesense) is in exactly the same position — same decided bullet, same @kirchdev/duxt-typesense in its own repository — so whichever way this is settled should settle both. Nothing has been written to #74 from here.

Verified while reading the issue, since it is cheap to lose

The constraint 059cd6a cites for the record id holds on current Meilisearch, checked rather than taken on trust:

• Meilisearch v1.53.2 (2026-09-07) is current; the JS client meilisearch is at 0.62.0.
• The documented rule is unchanged: a document id "can only contain alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and underscores (_)", and since meilisearch#4930 it must also be at most 511 bytes (an LMDB key limit).
• duxtSearchRecords emits a 32-character lowercase hex sha-256 prefix of url. That is [a-f0-9]{32} — inside the character class and 32 bytes against a 511-byte ceiling. No change to the hook is needed for Meilisearch, and the length limit is worth noting in docs/4.reference/12.hooks.md alongside the character rule whenever that page is next touched, because it is the half that is not obvious.

No record has been round-tripped into a real Meilisearch index. That remains unverified and cannot be verified from this loop: there is no instance and no credentials, and the issue's own policy makes the write key a build secret that must not be required of a consumer who is not using the provider.