Operator Support

This guide is for maintainers supporting early Scrypath production usage.

For metrics, paging discipline, and Meilisearch cluster footguns (SRE / platform view), see docs/search-backend-sre.md.

The support contract stays simple:

operator code calls the root APIs on Scrypath.*
terminal operators can use the thin mix scrypath.* wrappers over those same APIs
mix verify.phase14 keeps the core Mix task surface, docs contract, package metadata, and docs build aligned
mix verify.phase28 is the v1.5 index contract drift CLI plus operator-doc slice gate (runs focused tests then mix docs --warnings-as-errors)
mix verify.phase11 remains the release-contract gate

First Response Path

When a team reports drift, failed sync, or uncertain visibility:

ask which schema is affected
run mix scrypath.status for current visibility
run mix scrypath.failed for explicit recovery candidates
run mix scrypath.index.contract_drift YOUR_SCHEMA (or Scrypath.index_contract_drift/2) when the question is declared schema vs live index contract (fields, filterables, sortables, faceting, settings families) — distinct from queue failure triage alone
run mix scrypath.reconcile when you need report-first guidance before changing anything

Use mix scrypath.retry only when you already selected a concrete failed-work id.

Keep the sync mode in view during support:

:inline means Scrypath waited for terminal backend success, but database and search writes are still not atomic
:oban means the enqueue is durable, not that search visibility is complete
:manual means accepted work was handed back for operator-controlled follow-up

The detailed operator wording lives in guides/sync-modes-and-visibility.md.

Support docs should keep two boundaries explicit:

Do not document the Mix tasks as a replacement for the root API, and do not widen Scrypath.search/3 with Meilisearch-native flags.

Before merge or release handoff, run:

mix verify.phase14
mix verify.phase20
mix verify.phase26
mix verify.phase28
mix verify.phase11

Command	What it covers (auth-free)
mix verify.phase14	Thin mix scrypath. task wrappers, docs contract, package metadata, and *mix docs --warnings-as-errors
mix verify.phase20	Faceting, Meilisearch settings, faceted-guide docs contract, then mix docs --warnings-as-errors
mix verify.phase26	Failed-work rollups, reconcile output, operator Mix tasks, docs contract with --warnings-as-errors, then mix docs --warnings-as-errors
mix verify.phase28	Index contract drift CLI (`mix scrypath.index.contract_drift`), operator docs contracts for the v1.5 slice, focused tests with --warnings-as-errors, then mix docs --warnings-as-errors
mix verify.phase11	Release path: package metadata, clean-consumer smoke, release-doc contract, docs build, workflow checks, mix hex.build --unpack

mix verify.phase11 remains the gate you use before a real publish flow.