What area does this relate to?

An existing contribution (recipe, schema, dashboard, integration, skill)

What would you like to see?

recipes/schema-aware-routing

The recipe currently documents only OpenAI direct as the LLM/embedding provider (via LLM_API_URL=https://api.openai.com/v1, EMBEDDING_API_URL=https://api.openai.com/v1, OpenAI keys, model strings without provider prefix). Adding OpenRouter as a documented alternative would align this recipe with OB1's canonical setup and remove a friction point for users who've already followed the getting-started guide.

Why this matters

docs/01-getting-started.md Step 4 sets up OpenRouter as the canonical API gateway for OB1, used by the core MCP Edge Function for both embeddings and metadata extraction. Anyone arriving at this recipe via the standard OB1 path already has:

• An OpenRouter account
• An OPENROUTER_API_KEY configured as a Supabase secret
• $5+ in OpenRouter credits

Forcing them to additionally set up an OpenAI account, get an API key, fund it separately, and manage two billing relationships — purely for this one recipe — is unnecessary friction. It's also the path that surfaces the OpenAI service-account-key class of issues (per-key spend caps, project-level limits) that don't exist on OpenRouter at the personal-install scale.

Why it's drop-in

OpenRouter is OpenAI-compatible at both endpoints the recipe uses:

• POST https://openrouter.ai/api/v1/chat/completions
• POST https://openrouter.ai/api/v1/embeddings

Same JSON shapes, same Authorization: Bearer header pattern, same response_format: { type: "json_object" } support on openai/* models. The recipe's extractMetadata() and getEmbedding() functions already work as-is — only .env values change.

The canonical OB1 Edge Function (supabase/functions/open-brain-mcp/index.ts) already proves this combination by relying on it, using model strings openai/gpt-4o-mini and openai/text-embedding-3-small.

Proposed change

Pure documentation. No code edits to index.ts, config.ts, package.json, or any SQL.

1. Add an "Alternative: use OpenRouter (matches OB1 standard)" callout to setup-checklist.md Step 2

Show the four .env lines that change versus the OpenAI-direct setup:

# Alternative: use OpenRouter (matches canonical OB1 setup from docs/01-getting-started.md)
LLM_API_KEY=<your-OpenRouter-key>
LLM_API_URL=https://openrouter.ai/api/v1
LLM_MODEL=openai/gpt-4o-mini

EMBEDDING_API_KEY=<your-OpenRouter-key>
EMBEDDING_API_URL=https://openrouter.ai/api/v1
EMBEDDING_MODEL=openai/text-embedding-3-small
EMBEDDING_DIMENSIONS=1536

2. Mirror it in .env.example as a commented-out alternative block

So users see the option at the moment they're filling in credentials, not buried in setup docs.

3. Optional: brief mention in README.md Prerequisites

One line: "Either an OpenAI API key OR an OpenRouter API key (matches canonical OB1 setup) — see Step 2 for either path."

Verification

This was tested end-to-end during a personal install. The recipe was first verified against OpenAI direct (3 of 3 verification inputs from Step 7 pass), then the same install was swapped to OpenRouter via the .env changes above and re-verified (3 of 3 still pass). No code edits in either case.

Alternatives considered

• Make OpenRouter the primary documented path, OpenAI direct the alternative. Defensible since canonical OB1 setup uses OpenRouter, but it's a bigger doc change and a stronger statement than necessary. Letting both paths coexist with OpenAI-direct as primary preserves backward compatibility for anyone already running the recipe and treats this as additive.

• Add a PROVIDER=openai|openrouter env var with code-level switching in config.ts. Cleaner UX (one variable to flip) but adds code surface area, requires testing both paths in CI, and doesn't actually save the user any work — they still need to set the API key and (effectively) the model strings. Pure .env documentation is simpler and equally functional.

• Document only in a Troubleshooting section. Discoverable too late — the user is already mid-install with one provider when they'd see it. The Step 2 / .env.example callout catches them at the right decision point.

• Leave it as-is and let users figure out the swap themselves. Possible since OpenAI-compatible swaps are well-known to experienced developers, but OB1's whole pitch is "30 minutes, zero coding experience" — the recipe should match that expectation.