Skip to content

Find code by asking what it does. A CLI for coding agents that uses Jev to discover relevant files and source context.

docs: specify native TypeSafe and OpenRouter support

David Zhang3f9131615af4
diff --git a/specs/provider-support/README.md b/specs/provider-support/README.md
new file mode 100644
index 0000000..1a69c2a
--- /dev/null
+++ b/specs/provider-support/README.md
@@ -0,0 +1,146 @@
+# Saved-provider support
+
+Add native TypeSafe and OpenRouter to `jg`, using one TypeSafe-compatible AI SDK
+adapter for all three services. Choose the provider once during authentication;
+ordinary searches keep the same interface and retrieval behavior.
+
+## Next Agent Prompt
+
+You are implementing this plan, last updated 2026-09-26. **Status: specification
+only; no provider implementation or live verification has happened.** Start at
+[slice 1](slices/01-protocol.md): reproduce the pinned adapter against controlled
+HTTP before changing production. Read [the evidence](research.md) and
+[the preservation gates](parity.md). The completed [decision map](map.md) supplies
+user rationale; this README and its slices now own implementation order.
+
+You have no unresolved product question. Published-package behavior and live
+provider access need verification, not invented compatibility code. Missing
+credentials must not block offline implementation; report the missing live check
+honestly. Do not collect secrets in chat or overwrite the user's own saved setup
+for tests. Use isolated HOME/config/cache locations.
+
+- [ ] [1. Protocol reproduction and controlled routing](slices/01-protocol.md)
+- [ ] [2. Shared evaluator and production parity](slices/02-evaluator.md)
+- [ ] [3. Saved-provider auth, installed journeys, and onboarding](slices/03-auth.md)
+- [ ] [4. Maintained eval routing and final verification](slices/04-tooling.md)
+
+Update this prompt and the owning slice with evidence, remaining work and any
+deviations before ending each pass. Review each implementation slice before
+committing. Keep the checkout clean on main; do not create orphan worktrees or
+archive branches. There is no new benchmark run or npm publication in this plan.
+
+## Roadmap and review surfaces
+
+```mermaid
+flowchart LR
+ A[1: Prove SDK wire contract] --> B[2: Replace evaluator and prove parity]
+ B --> C[3: Choose and save provider in auth]
+ C --> D[4: Repair maintained eval routing and close checks]
+```
+
+| Slice | Question answered | Reviewable result |
+| ----- | ---------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| 1 | Does the pinned adapter implement the documented protocol? | Synthetic HTTP transcript and pass/fail probe |
+| 2 | Can the new transport preserve existing retrieval? | Built CLI reproduces the frozen corpus; failure and cache tests |
+| 3 | Does one setup reliably select the service? | Installed Docker auth → doctor → search for every provider, plus native smoke |
+| 4 | Does maintained tooling still observe the actual product? | Offline broker/receipt fixtures and final verification record |
+
+These are CLI/library checkpoints, with text transcripts as review artifacts.
+There is no visual design or screenshot deliverable. Human feedback is welcome
+but does not block reversible implementation; decide from the specified gates
+and record the reasoning if no feedback arrives.
+
+## Binding product contract
+
+`jg auth` asks **provider first, then hidden key**. It saves one
+`{provider, apiKey}` record. Re-running auth replaces that setup; searches and
+doctor use it until replaced. No automatic provider fallback, account registry,
+logout, or provider-switch command.
+
+For automation, use `jg auth --provider <vercel|typesafe|openrouter> --stdin`.
+The provider is mandatory with stdin. As a simplicity decision for this plan,
+`--provider` is accepted only together with `--stdin`; interactive auth always
+shows the picker. No provider/model/endpoint options on search or doctor.
+
+Credentials come only from the saved record. Provider API-key, endpoint and model
+environment variables cannot override it; XDG storage locations remain supported.
+Auth saves without a network call; doctor separately tests a synthetic question
+and identifies the saved provider. No secrets in stdout, exceptions or fixtures.
+
+**The sole required backward compatibility:** absence of the `provider` property
+means Vercel. Do not rewrite credentials during reads or require reauthentication.
+A present invalid value, including null, is an error. No migration command,
+format-version field, or preservation of environment-based authentication.
+
+The selected provider receives the same eligible repository content as before.
+Keep the existing head-friendly source packet, excerpts, stdout-only behavior,
+exit semantics, filesystem exclusions, optional parsers and skill research policy.
+No CLI report/trace files; only existing intentional auth/cache/skill persistence.
+
+## Single owners and scope boundaries
+
+| Concept | Owner |
+| ------------------------------------------------------------ | ------------------------------------------------------------------------- |
+| Fixed provider IDs, labels, endpoint/model/protocol identity | One small core preset module |
+| Saved key/provider, config paths, validation, atomic writes | CLI auth module |
+| HTTP attempts, retries, cooldown, answer validation | One evaluator using `@ai-sdk/typesafe-ai` |
+| Exact answer-cache storage | Existing cache module; evaluator supplies namespace |
+| Hierarchy, prompts, thresholds, batching, source freshness | Existing retrieval/request/source owners, unchanged |
+| Rendering and exit handling | Existing CLI owners |
+| Local HTTP redirection for verification | External test-owned Node preload, never packaged as product configuration |
+| Paid-call forwarding and raw accounting | Maintained benchmark broker/runner |
+
+No second evaluator, provider plugin registry, hand-written native client, or
+runtime protocol normalizer. Normalize transport only in tests. The intermediate
+Vercel-only CLI wiring in slice 2 disappears when slice 3 passes saved provider
+identity; it is not a compatibility layer to retain. Rename `gateway.ts` to
+`evaluator.ts` with its imports when replacing the implementation, leaving no
+forwarding module behind.
+
+Preserve the 50,000 **actual HTTP attempt** guard solely as runaway protection,
+SDK retries disabled, existing application retry/split policy, shared cooldown,
+cancellation and source freshness on every attempt. No performance tuning,
+prompt changes, new discovery strategy, parser changes, or benchmark optimization.
+
+## Acceptance and limits
+
+Each slice carries its focused gate. Final acceptance requires `bun run verify`,
+`bun run format:check`, and the native packaged smoke, with all-provider installed
+Docker journeys included in the normal suite. Freeze one candidate tarball and
+run it through both installed Docker and native checks, recording its SHA-256.
+Fixtures use actual SDK HTTP and installed CLI, not a mocked evaluator.
+
+Perform bounded synthetic live doctor checks for providers whose credentials are
+available through an authorized local source, using isolated saved records. Keep
+those results separate from offline checks; unavailable credentials mean live
+access is **unverified**, not failed or passed. A documented route that actually
+rejects its preset is a correctness issue to resolve before claiming support.
+
+Historical cost/quality claims retain their original scope. Jev cost is excluded
+from scored coding-agent task cost, but available observed billing is preserved
+separately; missing totals are unknown. No baseline reruns, personal-repo evals,
+fresh SWE-bench cohort, speed claim, release version selection, or npm tag push.
+
+## Plan audit
+
+Three blind read-only drafts informed this plan: a fewest-slices draft proposed
+one atomic change, a seam-focused draft proposed five stages, and Claude Opus's
+risk-first draft proposed eight. This plan takes their shared protocol-first
+gate, strict reference comparison and external routing seam. Four slices keep
+auth/retrieval/tooling independently reviewable without making docs or packaging
+separate workstreams. A single large slice would delay useful evidence; eight
+would leave too many small migration boundaries to maintain.
+
+Rejected alternatives: an internal baseURL override is unnecessary when fetch
+redirection is test-owned; a multi-provider benchmark runner expands this feature
+without helping product verification; interactive `--provider` adds a second way
+to skip the required picker. Keep only the stdin automation form. Package notices
+are part of the adapter/build gate, not deferred release cleanup.
+
+The interview was completed in the map, including the user's explicit legacy
+credential exception; no repeat permission or compatibility question is needed.
+The roadmap front-loads protocol evidence, then preserves the existing product
+before exposing additional auth choices. [Parity](parity.md) names each preserved
+behavior, its evidence and owning gate. [Research](research.md) distinguishes
+documented presets from unverified live access. Every slice names its remaining
+implementation discretion; a choice outside that list requires updating this plan.
diff --git a/specs/provider-support/map.md b/specs/provider-support/map.md
index aa7d0e3..7267892 100644
--- a/specs/provider-support/map.md
+++ b/specs/provider-support/map.md
@@ -1,8 +1,9 @@
# TypeSafe and OpenRouter support: decision map
Completed explore-unknowns walk, 2026-09-26. Territory inspected at `3cd6dc8`.
-This is the agreed map for implementation; it does not claim the providers have
-been implemented or live-tested.
+This preserves the exploration decisions. The [implementation spec](README.md)
+now owns sequencing and verification; no provider implementation or live testing
+is claimed here.
## Known knowns
@@ -104,22 +105,15 @@ broker, package metadata, and README/skill onboarding.
billing metadata. Preserve available raw observations and report unavailable
totals as unknown, never zero. Jev remains excluded from scored agent task cost.
- **Model identity and live behavior — OPEN verification.** Provider model names
- and aliases differ, and aliases can change their backing model. Before coding
- presets, confirm accepted IDs and the published adapter version's response/error
- contract. Before claiming live support, run bounded synthetic doctor checks
+ and aliases differ, and aliases can change their backing model. The subsequent [research record](research.md) resolves documented model IDs;
+ slice 1 still verifies the published adapter response/error contract. Before claiming live support, run bounded synthetic doctor checks
with each provider's credentials when available. No keys were read and no live
model calls were made during this walk. Missing access must be reported, not
replaced with a claim that fixtures prove service access or equal solve quality.
-## Implementation handoff
+## Superseded implementation handoff
-Keep this map updated if implementation uncovers a conflicting API contract.
-No paid benchmark repeat or release version is selected by this walk. Historical
-savings are evidence for their frozen candidates, not a guarantee for new routes.
-
-Copyable next request:
-
-> Implement this provider-support map. Preserve the retrieval policy, legacy saved
-> Vercel credentials, and the agreed single-provider auth flow. Verify protocol
-> parity, all-provider Docker journeys and native smoke; review, commit and push
-> cleanly to main. Report live-provider checks separately from fixture tests.
+The earlier request to implement directly from this map is superseded by the
+[spec README and Next Agent Prompt](README.md#next-agent-prompt). Follow its slice
+order and preservation gates. Keep this map as user-decision rationale, not a
+competing build plan. No paid benchmark repeat or release version was selected.
diff --git a/specs/provider-support/parity.md b/specs/provider-support/parity.md
new file mode 100644
index 0000000..606b35e
--- /dev/null
+++ b/specs/provider-support/parity.md
@@ -0,0 +1,42 @@
+# Preservation gates
+
+The immutable input tree and historical hashes are identified in
+[research](research.md). Keep the original oracle executable, corpus, manifest,
+manifest-covered files and prior studies byte-for-byte unchanged. The production
+harness may change its setup/routing; it must not loosen the expected result.
+
+| Preserved behavior | Existing evidence | Owner and acceptance gate |
+| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| Structured state, exact instructions and question IDs/order | `test/reference/requests.test.ts`, `corpus.json` | Slice 2: compare new-wire semantic requests to frozen corpus through built production CLI |
+| Hierarchy, thresholds, role/evidence/reference decisions | `test/reference/discovery-parity.test.ts`, `selection.test.ts`, `repository-context-parity.test.ts` | Slice 2: existing decision regressions remain green |
+| Full stdout, source selection/order and excerpts | `replay.test.ts`, `evidence-order.test.ts`, Python/comment parity tests | Slice 2: exact complete stdout plus existing ordering/parser tests |
+| Retries, cooldown, auth abort, timeout and attempt guard | `test/gateway.test.ts` | Slice 2: real native-wire HTTP failure matrix; rename test consistently if module renamed |
+| Source freshness on cache reads and every retry | `test/retrieval-freshness.test.ts` | Slice 2: mutation/deletion during wait cannot upload stale source |
+| Validated answer-only cache | `packages/core/test/cache.test.ts` and evaluator validation | Slice 2: same namespace hits; provider/endpoint/model/protocol differences miss; invalid/missing answers never cache as negative evidence |
+| Private atomic auth, cancellation and key validation | `apps/cli/test/auth.test.ts` | Slice 3: new/legacy records, replacement and failure paths; assert old bytes survive cancellation |
+| Installed runtime, ignores, signals, pipe closure, stdout-only | `test/installed.test.mjs`, `scripts/test-native.mjs` | Slices 2–3: actual packed CLI with controlled HTTP; all new provider cases selected by native gate |
+| Frozen research skill policy and installation | `test/reference/skill.test.ts`, release/skill tests | Slice 3: only setup/auth guidance changes, research body preserved |
+| Raw eval observations and honest missing billing | `evals/implementation/swebench/test_installed.py` | Slice 4: offline broker/receipt fixtures, frozen baselines/studies unchanged |
+
+## Permitted differences
+
+Assert native request destination, method, bearer auth, content type, model and
+full body independently **before** normalizing. The new SDK wire body contains
+`model`, `state`, and `questions`, with `noul` question types. The old reference
+body contains state/questions with boolean types and empty `providerOptions`;
+model identity is in Gateway headers. Accept only these documented transport
+changes and SDK-specific transport headers. Native noul answers must map to the
+same associated boolean probabilities. Unknown body/question fields must cause a
+fixture failure, not be silently dropped by a permissive normalizer.
+
+Production replay may reconstruct the old envelope for comparison after strict
+validation. Preserve state values and object/array ordering rather than sorting
+their contents or stringifying structured state. The existing corpus sorts whole
+request strings to ignore independent HTTP arrival order; it does not prove a
+global dispatch chronology. Retain separate deterministic decision/order tests.
+
+Auth/help/doctor text intentionally changes for provider setup. Successful search
+stdout under identical responses does not. Legacy credentials are read without
+mutation. Cache namespace intentionally changes; no old-wire answer reuse or
+cache migration is required. Live model outputs may vary and are not replaced by
+deterministic fixture claims.
diff --git a/specs/provider-support/research.md b/specs/provider-support/research.md
new file mode 100644
index 0000000..c8578ef
--- /dev/null
+++ b/specs/provider-support/research.md
@@ -0,0 +1,76 @@
+# Provider contract evidence
+
+Inspected 2026-09-26. These are documentation/source observations, not live service
+results. The implementation starts with a small adapter reproduction, not another
+retrieval experiment.
+
+## Fixed presets
+
+| Provider ID | AI SDK adapter base URL | Model sent in body | Evidence |
+| ------------ | ------------------------------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `vercel` | `https://ai-gateway.vercel.sh/typesafe/v1` | `typesafe-ai/jev` | [Vercel TypeSafe API](https://vercel.com/docs/ai-gateway/sdks-and-apis/typesafe) explicitly shows this model and `/typesafe/v1/systemone`. |
+| `typesafe` | `https://api.typesafe.ai/v1` | `jev-1.13.0` | [TypeSafe models](https://docs.typesafe.ai/models) documents the versioned ID; pin it because retrieval thresholds are calibrated. |
+| `openrouter` | `https://openrouter.ai/api/v1` | `jev-1.13` | [OpenRouter's Jev guide](https://openrouter.ai/blog/insights/what-is-jev/) documents the TypeSafe-compatible route and this bare model ID. |
+
+The native TypeSafe client examples use a base URL without `/v1`; the AI SDK
+adapter appends only `/systemone`, so its presets include `/v1`. Do not substitute
+OpenRouter chat completions or its separate `/api/alpha/decisions` API.
+
+Versioned native/OpenRouter names do not prove identical backends or answers to
+Vercel's alias. Preserve existing thresholds; do not claim cross-provider solve
+quality from transport fixtures. Record actual returned model identity in external
+probe evidence when available. A conflicting live API result goes into this plan
+before changing a preset; never silently try other providers/models.
+
+## Adapter identity and behavior
+
+Use `@ai-sdk/[email protected]` with the existing `[email protected]`, subject to the
+published-package reproduction gate in slice 1. Registry metadata inspected:
+
+```text
+dist.integrity = sha512-nP5NJGCwZ7jDE2dImurTU9igbj1OUeFAXLvZKcM05KlBpLxhOddBe3sMftAhQq3Zq+B8NqLx1dcW4vQVD2l32w==
+@ai-sdk/provider = 4.0.18
+@ai-sdk/provider-utils = 5.0.49
+```
+
+The official [provider source](https://github.com/vercel/ai/blob/main/packages/typesafe-ai/src/typesafe-ai-provider.ts)
+exposes `createTypeSafeAi({apiKey, baseURL, fetch})` and `evaluationModel(modelId)`.
+It has an environment-key default; always pass the validated saved key explicitly.
+The [evaluation implementation](https://github.com/vercel/ai/blob/main/packages/typesafe-ai/src/typesafe-ai-evaluation-model.ts)
+maps boolean questions to `noul`, posts structured state/questions with a model,
+and maps native answers back to boolean probabilities. Inspect the immutable npm
+artifact before treating moving GitHub source as the installed contract.
+
+## Billing and errors
+
+Vercel's compatible response documents `provider_metadata.gateway.cost` and
+`generationId`, with snake-case token usage. OpenRouter examples expose
+`usage.cost`, snake-case token usage, and a response ID. These are candidates for
+the maintained broker's raw-response decoder, not reasons to add CLI telemetry.
+Native TypeSafe billing may be absent. Unknown totals remain unknown; observed
+Jev billing stays separate from scored coding-agent task cost.
+
+The adapter's error classes differ from Gateway's. Slice 1 reproduces HTTP status,
+timeout, disconnect, and malformed-response behavior; slice 2 owns the mapping to
+existing retry/split semantics. Primary [TypeSafe API documentation](https://docs.typesafe.ai/api)
+and the Vercel guide describe native errors; fixtures must use their shapes.
+
+## Immutable preservation baseline
+
+Repository input: `ca7054ed4c50283030102d15cd73d816e85bc569`. This Git tree pins the
+current production implementation, lockfile, policy, parser versions, source tree,
+skill, test harness, and previously recorded evidence. The additional historical
+source hashes are owned by [the reference manifest](../../test/reference/manifest.json).
+Keep that manifest, its covered files, [the corpus](../../test/reference/corpus.json),
+and all historical benchmark results unchanged.
+
+The corpus compares a request multiset: independent network arrival order is not
+an invariant. Order inside state arrays and question objects, answer association,
+selection/evidence ordering, and complete rendered stdout are invariants. Keep
+existing decision/order regressions alongside semantic wire comparison; never
+serialize production concurrency to make a replay easier.
+
+The [corrected repeat](../done/jevgrep/assets/variance-repeat.md) is historical
+evidence, not a new-provider acceptance result. Baselines are immutable and are
+never rerun for this feature. Neither equal success rate nor fresh savings is
+established by this plan.
diff --git a/specs/provider-support/slices/01-protocol.md b/specs/provider-support/slices/01-protocol.md
new file mode 100644
index 0000000..329c11a
--- /dev/null
+++ b/specs/provider-support/slices/01-protocol.md
@@ -0,0 +1,65 @@
+# 1. Reproduce the provider protocol
+
+**Unlock:** prove the chosen SDK and controlled routing before touching retrieval.
+No dependency on another slice. Status: not started.
+
+## Seam and artifact
+
+Pin the adapter identified in [research](../research.md), inspect its published
+artifact, and use `experimental_evaluate` with structured synthetic state and two
+boolean questions. Send through the actual adapter to local HTTP fixtures for
+each documented preset. Keep the probe test-owned and add it to the ordinary test
+entry point; do not add a user-facing probe command or another native client.
+
+Keep `[email protected]` and the historical oracle's resolved dependency closure fixed.
+Adding the adapter may add its own provider-utils version; it must not silently
+upgrade the oracle through lockfile deduplication. Inspect the new dependencies'
+license files too: `scripts/package-notices.mjs` currently has an exact-version
+exception for `@ai-sdk/[email protected]`. Record whether the new artifact
+supplies its own license before changing that exception.
+
+The test transport seam is a Node `--import` preload outside the npm package.
+It observes the original fetch URL, allows only the three exact preset endpoints,
+then redirects to a local fixture preserving method, headers, body and abort
+signal. Unknown destinations fail closed. No production environment override,
+TLS bypass, or user config extension. For core tests the same narrow fetch
+redirection can be passed as a dependency. Test expectations remain independent
+of the production preset table so a wrong URL/model cannot validate itself.
+
+Save a concise `assets/protocol-verification.md` with package integrity, tested
+request/answer/error shapes and reproduction command. It contains synthetic data
+only. This is the first human review surface; no live credential is needed.
+
+## Verification and verdict
+
+- Assert exact endpoint suffix, model, bearer key, structured nested state,
+ question IDs/order/instructions, boolean-to-noul conversion, and finite answer
+ probability conversion. Inspect the pinned SDK's real response schema; provide
+ required response fields rather than bypassing its validator.
+- Reproduce 401/403, 408, 409, 429 with both Retry-After forms, 5xx, timeout, socket
+ disconnect, malformed JSON, missing and out-of-range answers. Record actual
+ error status/name/cause available to the application. No assumption that old
+ Gateway exception names survive.
+- Run through the current Node Docker reference harness. Prove cancellation
+ reaches real HTTP and no hidden SDK retries occur when `maxRetries: 0`.
+- Prove the preload rejects a wrong original destination and that fixture
+ redirects are not baked into the packed product. Keep original reference tests
+ green. No live calls or benchmark execution is required for this verdict.
+
+Acceptance: a reproducible adapter contract for all presets and observed error
+classification inputs. If the pinned package disagrees with its docs, resolve
+that concrete mismatch and update the research record before slice 2. Do not
+redesign transport around an assumption or change prompts/thresholds.
+
+## Decision budget
+
+Delegated: probe/fixture filenames, internal helper names, concise transcript
+format, and the smallest compatible package pin correction if the inspected
+artifact fails the stated API contract (record exact reason/integrity). Presets
+are the documented choices, not an invitation to pick newer aliases. Human
+feedback can change presentation of the transcript; an API contradiction changes
+the plan. Proceed on passing evidence without waiting for sign-off.
+
+An adapter requiring an `ai` upgrade, clamping invalid probabilities, or changing
+request meaning fails this slice. Reslice that concrete conflict before proceeding;
+do not hide it with a permissive fixture or silently alter the frozen oracle.
diff --git a/specs/provider-support/slices/02-evaluator.md b/specs/provider-support/slices/02-evaluator.md
new file mode 100644
index 0000000..185bd37
--- /dev/null
+++ b/specs/provider-support/slices/02-evaluator.md
@@ -0,0 +1,76 @@
+# 2. Replace the evaluator and prove production parity
+
+**Unlock:** one provider-neutral evaluator preserves the existing search contract.
+Depends on slice 1. Status: not started.
+
+## API seam and ownership
+
+Add one core preset owner exposing a `ProviderId` union (`vercel`, `typesafe`,
+`openrouter`) and immutable label/baseURL/model/protocol records from research.
+Rename `gateway.ts` to `evaluator.ts` and update consumers directly. Keep
+`EvaluationRequest`, the retrieval `Evaluator` interface and failure kinds stable.
+
+`createEvaluator` takes explicit `provider: ProviderId`, validated `apiKey`, and
+the existing cache/policy/signal/attempt settings. Resolve URL/model internally;
+remove the old general baseURL option. A fetch dependency may exist for core
+testing, but CLI users get no transport override. Always pass the key to
+`createTypeSafeAi`; never depend on SDK environment discovery.
+
+At this checkpoint CLI search/doctor pass Vercel explicitly: public setup remains
+Vercel-only until slice 3. Remove `AI_GATEWAY_BASE_URL` wiring now, and move
+production test routing to slice 1's preload. Slice 3 removes the explicit Vercel
+selection when saved credentials become the shared input. Do not add a temporary
+provider flag, dual evaluator, wrapper module, or dispatcher registry.
+
+Keep one owner of actual attempts and retries. Cache identity includes provider
+ID, effective endpoint, requested model, a native protocol identity and existing
+policy/parser/prompt identities. Cache storage/schema/TTL stay unchanged. Old-wire
+entries naturally miss; no deletion or migration is necessary.
+
+## Gates and review surface
+
+Implement the failure mapping from the published SDK evidence, preserving the
+existing application's behavior rather than copying only old error names:
+
+- SDK `maxRetries: 0`; one fetch increments one request. Guard remains 50,000.
+- Existing normal/navigation retry limits, navigation transient split eligibility,
+ special 429 handling and shared cooldown. Do not broaden retry policy incidentally.
+- Preserve the Node disconnect recovery checked by
+ `test/reference/disconnect.test.ts`. Distinguish transport failures from invalid
+ JSON/answers; do not classify every status-less exception as transient. Do not
+ inherit SDK `isRetryable` wholesale (for example, navigation 409 must not gain
+ a new retry/split merely because the adapter marks it retryable).
+- 401/403 abort in-flight siblings, cooldown waits and future attempts. User
+ cancellation/pipe closure stops work. Retry-time source validation still runs
+ after cooldown and before HTTP; invalid source never uploads again.
+- Missing/malformed/nonfinite/out-of-range answers remain failure/incomplete,
+ never negative evidence. Only validated answers enter cache.
+- Prove same-identity cache reuse and misses across provider, endpoint, model and
+ protocol identities without making those fields public CLI options.
+
+Apply [the parity contract](../parity.md) through the built production CLI as soon
+as the adapter is wired. Keep historical replay on its existing Gateway protocol;
+adapt only production setup and strict transport normalization. Keep the manifest,
+corpus, historical source and existing `replay.test.ts` assertions unchanged.
+Add provider-parameterized production parity cases without replacing the original
+Vercel comparison. Every provider must reproduce the same packet under identical
+controlled probabilities. Retain selection, source-order, comment and parser gates.
+
+Keep the package build green with the new adapter's actual bundled dependency
+notices. If a new upstream package omits a license, use a verified matching
+upstream license and record its provenance under the existing notices mechanism;
+never disable validation or apply the old version's exception indiscriminately.
+
+Run `bun run test:reference` plus the ordinary evaluator/cache/freshness tests and
+`bun run check-types`. Adapt installed Vercel fixture routing in this slice so
+`bun run test:installed` remains green; native fixtures share the same transport.
+Review the complete stdout packet and a request diff with only allowed transport
+changes. Record results in `assets/evaluator-verification.md`.
+
+## Decision budget
+
+Delegated: preset/type naming, error-inspection helper placement and cache protocol
+token spelling. Error classification must be justified by slice 1's observations;
+the retry policy itself is not delegated. No concurrency serialization, new
+retrieval logic or response truncation to pass parity. User feedback could change
+the chosen provider architecture; absent that, proceed on the frozen gates.
diff --git a/specs/provider-support/slices/03-auth.md b/specs/provider-support/slices/03-auth.md
new file mode 100644
index 0000000..96c380b
--- /dev/null
+++ b/specs/provider-support/slices/03-auth.md
@@ -0,0 +1,84 @@
+# 3. Save a provider and complete the installed journey
+
+**Unlock:** users can choose any supported service once and use ordinary `jg`.
+Depends on slice 2. Status: not started.
+
+## API and interaction
+
+The auth module owns `Credentials = {provider: ProviderId; apiKey: string}` and a
+single saved-credentials loader replacing `loadApiKey`. Core owns provider IDs and
+labels; auth owns config path/key validation and filesystem effects. Search and
+doctor pass the loaded record to the same evaluator. No separate resolution tree.
+
+Interactive `jg auth` uses the existing prompt library: select Vercel AI Gateway,
+TypeSafe or OpenRouter, then enter the provider's hidden key. Noninteractive auth
+requires `--provider` and `--stdin` together; reject unknown IDs, bare `--stdin`,
+bare `--provider`, and provider flags on every other command. Errors direct users
+to the right setup without printing a key. Both prompt and result use stdout.
+
+Retain the current config location and private atomic replacement. Save only
+`{provider, apiKey}` after both inputs validate; cancel/invalid input leaves the
+previous record untouched. Preserve the 8 KiB key/input bound, whitespace rules,
+0700 directory and 0600 file permissions. Check cancellation before replacement.
+No network during auth; successful text names the provider and points to doctor.
+
+Absent provider property normalizes in memory to Vercel. A present invalid value
+errors. Reads never rewrite bytes. Remove production API-key/endpoint/model env
+overrides and missing-key guidance recommending them. XDG paths continue working.
+
+Doctor retains its synthetic question, identifies the saved provider on success
+and actionable failure, and never uploads the user's repository. Search stdout
+and research policy remain unchanged. Reauth is the only supported way to replace
+the selected service; no per-query switching or failure fallback.
+
+## Installed acceptance
+
+Use real installed npm tarball binaries in the existing Node-only, network-isolated
+Docker harness. The preload redirects approved destinations to actual local HTTP;
+it does not fake the evaluator. All cases live in normal test entry points:
+
+- For each provider: stdin auth → inspect exact private record → doctor → search
+ → repeated cache hit; replace auth with another provider and prove a new call
+ using that provider/key. Auth itself makes zero calls.
+- Providerless legacy record: doctor/search use Vercel and file bytes stay intact.
+ Invalid present provider fails before HTTP, including null and empty string.
+- Conflicting environment keys/URLs/models cannot override a valid record;
+ environment-only setup cannot authenticate. Missing-credential fixtures use an
+ empty isolated config directory, not an empty environment key. No saved key leaks in diagnostics.
+- Invalid key/provider, stdin overflow, prompt cancel and SIGINT preserve previous
+ bytes and clean temporary credential files. Use a PTY for interactive provider
+ ordering, hidden entry and cancellation; it is test tooling, not a runtime
+ dependency. Exercise the noninteractive cases through the installed CLI too.
+- Retain existing filesystem, source freshness, partial failure, signal/EPIPE,
+ stdout/stderr and skill-installer coverage; no alternate provider traffic after
+ authentication/network failure.
+
+Expand the native smoke selector and asserted pass count so all new provider
+journeys actually execute. Copy the preload in normal/prebuilt Docker paths and
+native setup; keep it outside packaged files. The existing package must still run
+with Node alone, no host Python/Bun/rg/compiler requirement.
+
+## Onboarding and review
+
+Update root/packaged README, `docs/architecture.md`, help, `.env.example` if obsolete, and the shipped
+`skills/jevgrep/SKILL.md` setup section together. Explain provider-first auth,
+replacement, legacy saved-key behavior and removal of environment-only setup.
+Keep `jg skill` / `npx skills add dzhng/jevgrep --skill jevgrep` installation easy
+to find and CLI installation guidance intact. Never ask an agent to request a key
+in chat. Preserve the frozen research body, not merely its meaning.
+
+Human review surface: short auth/doctor transcript with fixture keys redacted and
+the complete search packet. Save verification in `assets/auth-verification.md`.
+Run auth/parser tests, `bun run verify`, format check and native packaged smoke.
+For live doctor use isolated saved records and authorized local credentials only;
+record provider/date/model when present and success/error without secrets. Clearly
+separate unavailable credentials from offline pass results. Missing live access
+does not block remaining implementation or authorize a provider fallback.
+
+## Decision budget
+
+Delegated: prompt wording, test PTY tooling and helper layout. Picker order is
+Vercel, TypeSafe, OpenRouter; no additional account UX. The documented automation
+grammar and saved-data compatibility are fixed. Human feedback can adjust wording
+or report a service incompatibility; passing offline evidence permits proceeding
+without waiting for approval.
diff --git a/specs/provider-support/slices/04-tooling.md b/specs/provider-support/slices/04-tooling.md
new file mode 100644
index 0000000..fa458e8
--- /dev/null
+++ b/specs/provider-support/slices/04-tooling.md
@@ -0,0 +1,67 @@
+# 4. Preserve maintained eval routing and close verification
+
+**Unlock:** the maintained harness can observe the actual installed product after
+environment-based auth is removed. Depends on slice 3. Status: not started.
+
+## Seam and scope
+
+Update only the maintained `evals/implementation/swebench/installed.py`, broker
+and their tests/supporting fixtures. Historical frozen runners, traces, result
+files, baseline records and studies are immutable. Do not run an agent benchmark.
+The coding-agent inference path remains unchanged; this slice concerns Jev calls.
+
+The existing harness remains Vercel-backed; adding a benchmark provider matrix is
+out of scope. Prepare an ordinary saved `{provider: "vercel", apiKey: brokerToken}`
+record in the isolated treatment container instead of API-key environment auth.
+Reuse the externally injected Node routing seam to send the exact Vercel native
+endpoint to model-egress. The broker keeps the real key, validates the permitted
+path/model and forwards to Vercel's documented TypeSafe-compatible route. It must
+not allow an agent-selected origin or leak real credentials into the container.
+
+Keep the preload/routing configuration harness-owned and include its bytes in
+the maintained candidate's freeze/identity inputs. It must not affect unrelated
+Codex inference requests. Runtime source bytes, skill and packed artifact remain
+the actual candidate; no patched CLI or hidden public env override. Frozen old
+studies retain their original broker code rather than adding runtime legacy paths
+to the new broker for hypothetical compatibility.
+
+Raw request/response observations remain external to the CLI and exclude auth
+headers. Decode available native billing/usage from retained bodies with explicit
+schema fixtures. Preserve support in the analysis decoder for historical Gateway
+observations, because reading old results is a real consumer. Do not rewrite them.
+Count missing/unmatched responses honestly: known subtotal can coexist with an
+unknown full total. Zero is valid only when explicitly observed, not a default.
+Jev cost/tokens never enter scored coding-agent cost; keep reporting available Jev
+observations separately. There is no token-count or timing optimization here.
+
+## Offline verification and final artifact
+
+- Extend maintained Python tests for saved credentials, preload freezing, accepted
+ route/model, rejection of wrong targets/tokens, raw capture and billing decode.
+ Use local fake upstreams; no paid calls or baseline reruns.
+- Check Vercel native `provider_metadata.gateway.cost`/generation ID, historical
+ `providerMetadata.gateway.cost`, snake-case usage, missing/invalid billing and
+ incomplete request logs. OpenRouter billing fixtures may cover `usage.cost`
+ without expanding the benchmark runner to additional providers.
+- Run the Python suite through `bun run test`; all normal regression suites must
+ still pass. Run `bun run verify` and `bun run format:check` after final changes.
+- Pack one final candidate using existing release tooling and record SHA-256.
+ Run `bash scripts/test-installed.sh --prebuilt <tarball>` and
+ `node scripts/test-native.mjs --prebuilt <tarball>` against those same bytes.
+ These are verification operations, not a release/tag/npm publish.
+- Review the full change with the repo review workflow and an independent Codex
+ review. Record actual gate results and per-provider live-check status in
+ `assets/final-verification.md`, then update the README handoff/checklist.
+
+Human review surface: small synthetic receipt showing agent cost and separate
+known/unknown Jev observations, plus the final verification record. No newly
+measured savings or success-rate claim. Report any live-provider access still
+unverified in final delivery.
+
+## Decision budget
+
+Delegated: fixture organization, exact preload mount location and decoder helper
+names. Credential replacement and network routing remain external harness
+operations; the product API cannot grow to simplify tests. A route requiring a
+new product setting is a plan violation to resolve, not an implicit permission.
+User feedback could authorize a future benchmark/release, but silence does not.