Add or update a provider preset

A preset pre-fills the Add Provider form. It does not implement a new protocol, auth flow, model discovery adapter, or backend OAuth provider. Research first; don't ask the user to supply names, URLs, or capabilities you can find yourself.

1. Read the contracts and find the provider

• Read repo AGENTS.md, packages/backend/data/provider-presets.json, the authoritative runtime schema packages/shared/src/provider-presets.ts, the published editor schema packages/backend/data/provider-presets.schema.json, and the catalog loader packages/backend/src/services/provider-presets.ts. Check nearby presets for naming and region conventions, but don't copy their compatibility settings as a default.
• Read references/quirks.md before assessing capabilities or interviewing the user. It covers the questions and semantics for each supported quirk field. Confirm the current schema and dispatch code still agree with it.
• Inspect the picker, applyProviderPreset, endpoint URL construction, model discovery, and pi-ai registry/auto-compat dispatch when relevant. Only edit the catalog for a normal preset request; if the provider needs a protocol or auth mechanism Plexus doesn't support, explain the gap rather than inventing a preset that can't work.
• Search official provider docs (API reference, auth/setup guide, regional or product-specific docs) for exact identity, branding, docs URL, regions/hosts, credential type and headers, base URLs, model IDs, and supported inference endpoints. Follow the docs to each actual method/path; a generic "OpenAI-compatible" claim does not establish Messages, Responses, embeddings, or every region. Check conflicting or stale docs against other primary sources. Cite URLs next to claims.

2. Build an evidence-backed proposal

• For each candidate apiBaseUrl key, write down its official request method/path, auth, base URL as Plexus stores it, and evidence status: documented, safely probed (state exactly what that proves), or unknown. Plexus appends the transformer's endpoint suffix (for example /chat/completions, /messages, /responses); don't store the full request URL or omit an Anthropic-compatible /v1 segment merely because its SDK uses a different base. Check the actual transformer for variable paths such as Gemini or images. Only include protocols Plexus can route and the provider documents on that host/region. A documented route doesn't prove any specific model accepts it or supports reasoning.
• When docs identify a route but behavior remains unverified, an optional, low-impact probe may compare an invalid-key request to that path against a deliberately nonexistent path on the same host, using the documented method and comparable headers. Do not send real credentials, prompt data, or billable requests. A 401/403 can be generic auth-before-routing; 404 on GET can just be a method mismatch; a differing auth error still doesn't prove working inference. Record the observation and limit. Never claim a successful 200 or working paid call from an invalid-key probe. Leave merely plausible paths out. experimentalApis is only for upstream-documented keys the user knowingly chooses to include with an "Unverified endpoints" warning, not invented paths; it must be a subset of apiBaseUrl. An invalid-key control is not live verification of inference.
• Separate provider model discovery from pi-ai model lookup. Configured-provider discovery derives /models from chat or messages bases and may fail on custom paths/headers; a preset alone doesn't add a discovery adapter or configured models. Use GET /v0/management/pi/providers to check builtin IDs and GET /v0/management/pi/models?provider=<id> for pi-ai catalog models when a management server is available; otherwise inspect the installed pi-ai catalog. These are not upstream account model discovery. Record a documented /models URL in research findings when useful, not in a made-up modelsUrl or capability-probe preset field. pi-ai IDs help map already configured models, but don't establish account entitlement.
• Determine whether piAiProvider is a real pi-ai builtin ID with suitable model records and compatible wire behavior (not just a similarly named preset), whether explicit piAiQuirks are warranted, or whether neither is supported by evidence. The sources are mutually exclusive. Builtin auto-compat only applies when the configured model resolves to a pi_ai_model_id in that provider's catalog; inline overrides match exact upstream model IDs and configured target types. autoCompat is opt-in, not inferred from generic API compatibility, and requires one of those sources. Without a valid source leave it off; don't borrow OpenRouter's ID or assert "no quirks" just because fields aren't documented.
• Check the actual api dialect on each builtin model against each target it will serve. A real pi-ai provider may list a model only under Messages while the preset also offers Chat; auto-compat projects the model record's dialect, not the selected endpoint's dialect. Treat a mismatch as a blocker until the projected request is supported on that target, not as proof that the provider name is correct.
• For every proposed target protocol and each relevant model or model-family exception, walk through the reference's field checklist with the user. Show a researched disposition, source, and proposed value (or unknown/not applicable) separately for reasoning, thinkingLevelMap (including off/unsupported levels), maxTokens, compat.thinkingFormat, compat.supportsTemperature, compat.maxTokensField, compat.forceAdaptiveThinking, and compat.supportsReasoningEffort. Decide target-level traits versus exact-model overrides. Unknown is not false. Don't add a field without evidence that the provider accepts the resulting wire behavior. For builtin mode, explain that pi-ai supplies these traits and show which provider/model records actually match rather than fabricating inline values. Keep auto-compat off or restrict protocol/model scope when an unknown would make it unsafe.
• Check whether setup requires an account ID, gateway, region, project, deployment, or header. Use templateVars only for setup values interpolated as {key} in apiBaseUrl (every placeholder declared and every var used), never credentials. The preset cannot set arbitrary auth headers or API-key placement; ask about requirements beyond standard auth and flag backend work if needed. Use notes for concise, operator-visible setup caveats, not a research log. docsUrl and URL bases must be HTTPS.

3. Interview, then edit

• Present a compact proposal before editing: identity and region, protocol → stored base/path → evidence table, auth and setup inputs, model discovery limitations, pi-ai source/auto-compat decision, and the per-target/model quirk checklist from the reference. Link official sources and label probe observations separately. Ask the user to review and correct each relevant quirk conclusion, including documented ones, not just say whether the provider has quirks. Keep track of unknown fields and model exceptions across the conversation.
• Ask missing setup details and disputed choices in short, targeted batches, using the questions in references/quirks.md. Don't request API keys. Ask the user to confirm the findings and intended scope. If an unknown could change endpoints, region, auth, model behavior, or auto-compat, wait for the answer before editing; if the user can't confirm, propose an evidence-limited entry or omit the uncertain part and get that scope confirmed. Don't declare success on research alone.
• After answers, add or update the entry in packages/backend/data/provider-presets.json using established ordering/format. Preserve the stable id for updates, keep suggested provider ID/name distinct from pi-ai's ID, and include only schema-supported fields. Do not add an OAuth implementation or change shared/editor schemas for ordinary catalog data. If the request requires backend changes, follow the relevant repo rules rather than hiding the gap in the preset.

4. Validate what users will get

• Run bun run check:provider-presets-schema from the repo root (editor schema parity, JSON Schema, runtime parsing, duplicate IDs), then the relevant repo checks required by AGENTS.md. Don't regenerate the editor schema just to make a catalog change pass.
• Smoke-load the local catalog through loadLocalPresets, select the changed entry by id, and apply it to a blank draft with applyProviderPreset. Inspect resulting endpoint map, target types, selected quirk source, auto-compat setting, suggested fields, and unresolved URL templates. If a dev server is already available, also inspect GET /v0/management/provider-presets and its source; don't present a remote response as proof of an unmerged local edit.
• Report the entry, evidence limits, checks and smoke result. The management endpoint normally fetches the catalog from main on raw GitHub and falls back to the local file (embedded in release binaries). An unmerged branch edit is not the remote catalog; remote availability after merging depends on main, while older binaries retain an older embedded fallback until rebuilt. Locally edited disk files can take precedence over remote after server startup. Don't claim deployment or live upstream success without observing it.