Fail loud on missing local-embedding peer dep + ship -local Docker image (#88)

[jpr5]

Closes the local-embeddings half of #88. (The schema half shipped in v1.16.0.)

@xenova/transformers is an optional peer dep absent from the published Docker image, so provider: local failed — and failed silently in the common path. This PR makes it fail loudly and ships a supported Docker path. Three independent units; the authoritative design spec is included in the branch (docs/superpowers/specs/2026-06-25-local-embeddings-88-closeout-design.md).

Unit 1 — fail loud + fix validate semantics

• Startup guard: serve now eagerly resolves @xenova/transformers at boot when embedding.provider === "local". If absent, the process exits non-zero immediately with an actionable message (install the peer or use ghcr.io/copilotkit/pathfinder:latest-local). Previously it booted fine and threw lazily at first embed.
• validate semantics: the optional-dep check now routes to a new result.warnings[] field instead of result.errors[], so validate exits 0 when only warnings exist (it's a static linter; the startup guard is the real enforcement). The "Optional Dependencies" display block and the schema early-return are unchanged.
• A single shared resolveLocalEmbeddingDep() / assertLocalEmbeddingDepForProvider() helper (with one LOCAL_EMBEDDING_DEP_MESSAGE) backs both the startup guard and validate.
• Unit tests added: startup guard (local+absent→fail, local+present→ok, non-local+absent→ok) and validate exit-0-with-warning.

Unit 2 — -local Docker image variant

• Dockerfile: added ARG INCLUDE_LOCAL_EMBEDDINGS=false to the prod stage; after npm ci --omit=dev, conditionally npm install @xenova/transformers only when the arg is true. Default build stays slim.
• publish-docker.yml: the single build is now two variants in the same run from the same Dockerfile with disjoint tags — default (slim) → :latest, :<ref>; local (INCLUDE_LOCAL_EMBEDDINGS=true) → :latest-local, :<ref>-local. Both multi-arch, shared type=gha cache, one Slack notify summarizing both. The workflow_call/workflow_dispatch/push:tags triggers and tag-resolution step from Fix broken release→Docker publish pipeline (stale :latest at v1.15.0) #130 are preserved.

Unit 3 — docs

• docs/deploy: notes :latest-local ships @xenova/transformers preinstalled and that the default image now fails loudly at startup for provider: local.
• docs/config: cross-references the -local image vs npm install for the local provider.
• README.md: one-line pointer to the -local image.

---

Local RED→GREEN proof (real surfaces)

All runs used a schema-valid provider: local config with @xenova/transformers genuinely ABSENT from node_modules.

Unit 1 — startup guard (serve)

• RED (origin/main code, rebuilt to dist): serve boots past the embedding config with no mention of @xenova/transformers (grep count 0) and only dies later on the DB connection (ECONNREFUSED) — i.e. with a reachable DB it would boot a healthy-looking server that explodes at first embed.
• GREEN (this branch): serve exits 1 at boot:

  [startup] fatal: Error: embedding.provider is "local" but the optional peer dependency
  @xenova/transformers is not installed. Either install it (npm install @xenova/transformers)
  or use the prebuilt image ghcr.io/copilotkit/pathfinder:latest-local, which ships it preinstalled.
  

Unit 1 — validate exit code

• RED (origin/main): validate on the schema-valid local config prints Result: 1 optional dependency warning(s), no hard errors. yet exits 1 (the self-contradiction).
• GREEN (this branch): same config, same printed line, exits 0.

Unit 2 — Docker variants (built locally before CI)

• docker buildx build --build-arg INCLUDE_LOCAL_EMBEDDINGS=true --target prod -t pf:local . → docker run --rm pf:local node -e "require.resolve('@xenova/transformers')…" → PRESENT
• docker buildx build --target prod -t pf:slim . → same probe → ABSENT

Test suite

Full npx vitest run (excluding **/.claude/**): 171 files / 3192 tests passed, 0 failures. Prettier --check clean, tsc build clean, tsc -p tsconfig.scripts.json clean, version-sync in sync. No as any.

---

A follow-up release ships the -local image and the startup guard (the matrix docker build only runs on release/dispatch, not on this PR — so PR CI here is Static Quality only). Do not merge as a release commit.

🤖 Generated with Claude Code