melchizedek-agents 1.11.1 → 1.13.0

package/.env.example

@@ -2,7 +2,38 @@
 # asks what you have and prints the names to set for it; --auto detects it.
 # Only names and shapes live here: type the values yourself, never commit .env.
 
-# ── Required for cloud models ─────────────────────────────────────────────────
+# ── The quickest start: ONE gateway key for every cloud model ─────────────────
+# A Vercel AI Gateway or OpenRouter key serves every cloud model id whose
+# direct key is absent (Claude, GPT, Gemini, Grok, Kimi, DeepSeek, and
+# TypeSafe Jev on the gateway's System One route), billed to that one account.
+# Set these two and every multi-provider syndicate runs. By default a direct
+# key set beside it wins for its own provider, at full fidelity: native search
+# tools are dropped on the gateway path (the doctor says which), and the
+# gateway never serves ollama/* models; it embeds for long-term memory only
+# where it carries the same model (Vercel does; OpenRouter has no Gemini one).
+# MODEL_GATEWAY_PREFER=gateway turns that round (every cloud id through the
+# gateway, one bill), and MODEL_GATEWAY_EXCEPT names the providers that take
+# the opposite of the preference, e.g. gemini kept on its own key for grounding.
+# What a gateway gives back: web_search runs as the gateway's own search on
+# any model (Vercel's exa_search server tool; OpenRouter's web plugin, the
+# provider's native search where it has one, with citations), and long-term
+# memory embeds through the gateway when it carries the same embedding model
+# (Vercel: google/gemini-embedding-001). x_search and Collections stay direct-only.
+# A gateway is for billing and breadth, not for grounding: for a search-heavy
+# agent keep the provider that does the searching on its own key and let the
+# gateway serve the rest (a direct key beside the gateway key does that by
+# default; MODEL_GATEWAY_EXCEPT keeps it so under MODEL_GATEWAY_PREFER=gateway).
+# Keys: https://vercel.com/ai-gateway or https://openrouter.ai/keys
+# MODEL_GATEWAY=vercel            # or openrouter
+# MODEL_GATEWAY_API_KEY=
+# MODEL_GATEWAY_PREFER=direct     # or gateway: the gateway wins even beside a direct key
+# MODEL_GATEWAY_EXCEPT=           # optional: providers that take the opposite of the preference, e.g. gemini,xai
+# MODEL_GATEWAY_SEARCH=           # optional: off, or the gateway's engine (Vercel: exa | perplexity | parallel | browserbase | tako; OpenRouter: native | exa | firecrawl | parallel | perplexity)
+# MODEL_GATEWAY_SEARCH_RESULTS=3  # optional: results per search, folded into the prompt as input tokens (Exa pages run 2k-10k tokens each; perplexity caps tokens)
+# MODEL_GATEWAY_BASE_URL=         # optional: a self-hosted proxy speaking the same chat-completions dialect
+# MODEL_GATEWAY_MODEL_MAP=        # optional: "claude-sonnet-4-6=anthropic/claude-sonnet-4.6,jev-latest=typesafe-ai/jev,..."
+
+# ── Required for cloud models (without a gateway) ─────────────────────────────
 # Google AI Studio API key — powers all Gemini model inference.
 # Also required for the gemini-embedding-001 embedding model used by long-term memory.
 # Get yours free at: https://aistudio.google.com
@@ -102,6 +133,19 @@ MOONSHOT_API_KEY=
 DEEPSEEK_API_KEY=
 # DEEPSEEK_BASE_URL=   # a proxy speaking the same chat-completions dialect
 
+# ── Optional: TypeSafe Jev (a decision model, not a chat model) ──────────────
+# Required only when using jev-* model identifiers in YAML (jev-latest is the
+# alias for the newest release; jev-1.14.0 and jev-1.13.0 are the ids). Jev
+# answers an agent's output.schema as typed decisions with calibrated
+# probabilities, at $0.042 per million input tokens and nothing for output;
+# it writes no prose, calls no tool and shows no reasoning, so it is the model
+# of a classifier agent (examples/classifier.yaml), never of an orchestrator.
+# Get your key at: https://console.typesafe.ai/keys. Without it, MODEL_GATEWAY
+# serves jev-* ids on the gateway's System One route (typesafe-ai/jev on
+# Vercel, typesafe/jev-1.14 on OpenRouter).
+TYPESAFE_API_KEY=
+# TYPESAFE_BASE_URL=   # a proxy speaking TypeSafe's System One wire
+
 # XAI_COLLECTION_IDS: comma-separated xAI Collection ids searched by the
 # `collections_search` tool (grok-* agents only). Create collections and
 # upload documents at console.x.ai. Declared with no ids set, the tool is
@@ -320,15 +364,6 @@ MCP_WIKI_PORT=
 # string (gemini-*, claude-*, ollama/*, ...). Default: gemini-3.8-flash.
 WIKI_AGENT_MODEL=
 
-# ── Optional: one gateway key for providers you have no key for ───────────────
-# A model whose direct key is ABSENT is served through the gateway's OpenAI-
-# compatible endpoint (native search tools are dropped on that path; the
-# doctor says which). A present direct key always wins.
-# MODEL_GATEWAY=vercel            # or openrouter
-# MODEL_GATEWAY_API_KEY=
-# MODEL_GATEWAY_BASE_URL=         # optional: a self-hosted proxy speaking the same dialect
-# MODEL_GATEWAY_MODEL_MAP=        # optional: "claude-sonnet-4-6=anthropic/claude-sonnet-4.6,..."
-
 # ── Optional: tracing ─────────────────────────────────────────────────────────
 # Send every span to any OTLP/HTTP backend (Phoenix, Langfuse, Jaeger, Tempo):
 # a local Phoenix is `docker run -p 6006:6006 arizephoenix/phoenix`.
@@ -378,6 +413,14 @@ WIKI_AGENT_MODEL=
 # Fact extraction runs on any model id (routed like an agent's model); the
 # embedder is gemini (default), openai, ollama or any OpenAI-compatible
 # endpoint. The dimension must match the vector column (768 in db/migrations).
+# With no key for the embedding provider, or MODEL_GATEWAY_PREFER=gateway, the
+# embedder goes through the gateway when it carries the same model (Vercel does
+# for gemini-embedding-001; OpenRouter has no Gemini one: set
+# MEMORY_EMBEDDING_PROVIDER=openai to embed text-embedding-3-small at 768 through
+# it). The store records the model its vectors come from on the first write
+# (migration 0023) and refuses a different one at start: switching models means
+# re-embedding every stored fact, never mixing them. `npm run doctor` says what
+# would embed here.
 # MEMORY_EXTRACTION_MODEL=gemini-3.8-flash
 # MEMORY_EMBEDDING_PROVIDER=gemini
 # MEMORY_EMBEDDING_MODEL=

package/AGENT_SETUP.md

@@ -74,7 +74,10 @@ After the agent reports back:
    `OPENAI_API_KEY` for `gpt-*` (https://platform.openai.com/api-keys),
    `XAI_API_KEY` for `grok-*` (https://console.x.ai),
    `MOONSHOT_API_KEY` for `kimi-*` (https://platform.moonshot.ai),
-   `DEEPSEEK_API_KEY` for `deepseek-*` (https://platform.deepseek.com/api_keys). Not sure which
+   `DEEPSEEK_API_KEY` for `deepseek-*` (https://platform.deepseek.com/api_keys),
+   `TYPESAFE_API_KEY` for `jev-*` (https://console.typesafe.ai/keys; a decision
+   model for classifier agents). Or one `MODEL_GATEWAY` + `MODEL_GATEWAY_API_KEY`
+   (Vercel AI Gateway or OpenRouter) for every cloud id at once. Not sure which
    you need? `npm run doctor` reads every syndicate and prints what is
    ready, what is blocked, and which variable unlocks what — read-only,
    no key value shown. Verify the whole multi-provider surface live with

package/CHANGELOG.md

@@ -4,6 +4,131 @@ Consumers of the package read this file; it records changes to the
 **published API surface** (the exports map in `package.json`, the bins,
 the starter pack and the templates), not the repo's full history.
 
+## 1.13.0 — 2026-10-24
+
+**A Prompt Writer template.** `templates/prompt_writer.yaml` writes
+production prompts for an agent or a whole syndicate from a plain
+description, or diagnoses and rewrites a prompt someone pastes. An Editor
+runs a bounded loop: an Architect settles the topology, capabilities and
+trust boundary on a design sheet, a Writer writes every prompt in the
+Lyceum block anatomy (tool and MCP doctrines, subagent descriptions,
+`require_approval` on writes, one `[NEEDS: …]` variable per missing fact),
+and an Auditor checks it against a ten-rule checklist (`prompt_checklist`)
+and, when YAML is asked for, a verified skeleton (`yaml_shape`). Every
+agent runs on `gemini-4-argon`; session memory keeps the design across
+turns. Its prompts were written by `gemini-4-argon` from the course's
+lessons. Run live 2026-10-23: a two-agent MCP design whose YAML loads, a
+prompt repair that the Auditor sent back once, and the off-topic reply.
+
+## 1.12.0 — 2026-10-23
+
+A minor release: TypeSafe's Jev joins the providers as a decision model, and
+one gateway key is the first thing the setup offers.
+
+**TypeSafe Jev is a provider** (ADR 0144). `jev-*` ids route to the new
+`JevAdapter` (exported from `melchizedek-agents/model`, beside
+`DeepSeekAdapter`), against `https://api.typesafe.ai/v1/systemone` with
+`TYPESAFE_API_KEY` (`TYPESAFE_BASE_URL` for a proxy); `jev-latest` is the
+default (`DEFAULT_JEV_MODEL`). Jev is not a chat model: it answers an
+agent's `output.schema` as typed decisions with calibrated probabilities,
+in about a tenth of a second, at $0.042 per million input tokens and nothing
+for output. The schema is the request: a boolean property becomes a yes/no
+question, a string with `enum` or a `oneOf` of described constants a
+choice, an integer whose `oneOf` describes the levels 0..n-1 a score; the
+instruction and the conversation are the state; the final is the schema's
+object with the raw answers under a reserved `jev` key. The same call from
+code is `decide()`, typed on its questions (`noul`, `choice`, `score`), with
+`questionsFromSchema` and `objectFromAnswers` beside it. Jev takes no tools,
+no reasoning, no streaming and no images, and says so in the capability
+matrix; an agent with no schema, or with a property Jev cannot decide, fails
+before any call (`TYPESAFE_SCHEMA_REQUIRED`, `TYPESAFE_SCHEMA_UNSUPPORTED`,
+naming the property). The starter pack gains `classifier.yaml`, a
+support-triage classifier on `jev-latest` (`npm run syndicate:classifier`).
+The doctor, the setup guide (`ONBOARDING.md`), `.env.example`, the
+`model_overrides` keys (`typesafe`), the onboarding skills and the skill
+briefs know it. Run live through Vercel AI Gateway (the classifier and
+every id, 2026-10-23); TypeSafe's own API and OpenRouter not yet.
+
+**A gateway serves Jev too.** With no `TYPESAFE_API_KEY`, `MODEL_GATEWAY`
+serves `jev-*` ids on the gateway's own System One route: Vercel AI
+Gateway's `/typesafe/v1/systemone` as `typesafe-ai/jev`, OpenRouter's
+`/api/v1/systemone` as `typesafe/jev-1.14` (`MODEL_GATEWAY_MODEL_MAP` fixes
+an id). The gateway's `slugs` table has a `typesafe` entry and each gateway a
+`systemOne` route (`GatewayInfo`).
+
+**The gateway settings read through the credential source.**
+`MODEL_GATEWAY`, `MODEL_GATEWAY_BASE_URL` and `MODEL_GATEWAY_MODEL_MAP` are
+read with `credentialValue`, as the key already was (ADR 0133), so an
+embedding application that holds them in a keychain, not the environment,
+turns the gateway on too.
+
+**The gateway can come first** (ADR 0145). `MODEL_GATEWAY_PREFER=gateway`
+sends every cloud id through the configured gateway even beside its direct
+key (one bill, one dashboard); `MODEL_GATEWAY_EXCEPT=gemini,xai` names the
+providers that take the opposite of the preference either way (Gemini kept
+on its own key for grounding under `prefer=gateway`; Grok sent through the
+gateway under the default). Unset, nothing changes: a direct key wins.
+Ollama and an A2A caller's own key stay direct; a preferred path that is
+not funded falls back to the other; the doctor names a misspelt preference
+or an unknown provider. `gatewayPreference`, `gatewayExceptions` and
+`providerTransport` are exported from `melchizedek-agents/registry`.
+
+**A gateway searches and embeds** (ADR 0146). On the gateway path an
+agent's `web_search` is no longer dropped: Vercel AI Gateway runs its
+server search tool (`vercel:exa_search` by default) and OpenRouter its web
+plugin (the provider's native search where the model has one, else Exa),
+whose `url_citation` annotations the chat-completions base now keeps as the
+final's `grounding.citations` (`groundingOf`). `MODEL_GATEWAY_SEARCH` names
+the engine or turns it off; `x_search` and `collections_search` stay
+dropped. Long-term memory's embedder goes through the gateway's
+`/embeddings` when the gateway carries the same model (Vercel:
+`google/gemini-embedding-001`, `openai/text-embedding-3-small`; OpenRouter:
+OpenAI's) and the provider's own key is absent or the gateway is preferred,
+so the vectors stay the model's own. `GatewayInfo` gains `search` and
+`embeddings`; `gatewaySearch`, `gatewaySearchProblem` and
+`gatewayEmbedding` are exported from `melchizedek-agents/models/gateway`;
+`gatewayConfig`, `gatewayPreference`, `gatewayExceptions` and
+`gatewayWanted` take an optional `env`. The capability matrix's gateway
+row reads `native_search` as degraded, with the note.
+
+**A gateway's search is bounded, and a memory store can be re-embedded**
+(ADR 0148). `MODEL_GATEWAY_SEARCH_RESULTS` (default 3) is passed as each
+gateway search engine's count, Exa on its instant type and Perplexity under
+a token cap, since the results are billed as prompt tokens (an unbounded Exa
+search measured about 20,000 of them). `npm run memory -- reembed` re-embeds
+every stored fact with the environment's embedder in id-ordered pages and
+records the new model last (`MemoryStore` gains `listFacts`,
+`updateEmbeddings`, `setEmbedder`; migration 0023 gains
+`melchizedek_memory_set_embedder`), under an advisory lock on
+`DATABASE_URL`. The setup note and the env template state the posture: a
+gateway is for billing and breadth, not for grounding; keep the searching
+provider on its own key. The lockfile moves `body-parser`, `fast-uri` and
+`ip-address` past their advisories (no API change).
+
+**A memory store records its embedding model; the doctor says what embeds**
+(ADR 0147, migration `0023_memory_embedder`). On its first successful write
+the memory service records the provider, model and dimension the store's
+vectors come from, and at start it refuses an embedder whose model differs,
+naming the recorded one and the two ways out (set the embedder back, or
+re-embed every fact); a gateway's spelling of the same model passes. The
+doctor gains a `memory` line from `embedderPlan` (exported from
+`melchizedek-agents/memory`): what embeds long-term memory, on which path,
+or what to set, with OpenRouter's documented answer
+(`MEMORY_EMBEDDING_PROVIDER=openai`, `text-embedding-3-small` at 768) and
+the re-embed caveat (`memoryProvidersFromEnv` is exported there too). `MemoryStore` gains optional `embedderRecord` and
+`recordEmbedder`; `db/hardening.sql` locks the new table like the others.
+
+**One gateway key is the first thing offered.** `.env.example` opens with
+the `MODEL_GATEWAY` block (one Vercel AI Gateway or OpenRouter key for every
+cloud model whose direct key is absent), the README's cloud quick start
+leads with it, and the keys onboarding skill suggests it first when a person
+has no preference. The routing rule is unchanged: a direct key beside it
+always wins for its provider.
+
+**Price rows for Jev** (migration `0022_typesafe_jev_pricing`): `jev-latest`,
+`jev-preview`, `jev-1.14.0` and `jev-1.13.0` at $0.042 input, $0 output. An
+existing row is never overwritten.
+
 ## 1.11.1 — 2026-10-22
 
 **Price rows for `grok-4.3`, `gemini-embedding-001` and `gemini-3.5-flash`**

package/DOCUMENTATION.md

@@ -143,7 +143,7 @@ Field reference:
 | `reasoning` | agent | How hard the agent reasons, on any provider: `none`, `low`, `medium`, `high`, `xhigh`, `max`, or `{ budget_tokens: <int> }`. The compiler sends each provider the field it reads: a thinking level on Gemini 3, a thinking budget on Claude 4.6 and earlier (2,048 / 8,192 / 16,384 tokens for low / medium / high), adaptive thinking with that effort on later Claude models ([ADR 0049](./wiki/decisions/0049-claude-requests-by-model-generation.md)), an effort word on GPT, Grok, Kimi, DeepSeek (beside its thinking switch), Ollama and the gateway ([ADR 0047](./wiki/decisions/0047-provider-neutral-reasoning-key.md)). `xhigh` and `max` reach the models that take them (both on Claude from Opus 4.7 and Sonnet 5, `max` on Kimi K3, `xhigh` on GPT-5.2 and later and grok-4.7); elsewhere the model's highest setting is sent and the span carries `llm.reasoning.weakened` (`npm run doctor -- --matrix` lists each path, [ADR 0117](./wiki/decisions/0117-tool-choice-and-effort-above-high-in-v2.md)). Unset, each adapter keeps its own default. |
 | `sampling` | agent | `{ temperature, top_p, max_output_tokens, stop }`, the fields the engine sends to every provider; each adapter sends the ones its API takes ([ADR 0115](./wiki/decisions/0115-yaml-schema-v2-provider-neutral-keys.md)). |
 | `output` | agent | `{ schema, mime }`. `mime` is `application/json` (JSON mode, with or without a schema) or `text/plain` (the default). `schema` is the structured-JSON contract: the agent ends its turn on one JSON object matching it. An orchestrator may hold one beside its subagents: it delegates first, then answers in the schema itself. The schema travels in the provider's own structured-output field beside the tools on Claude from Opus 4.8, Sonnet 5 and Haiku 5.5, on OpenAI, and on Gemini 2+ through Vertex AI, and as a `set_model_response` tool elsewhere (the capability matrix's `structured_output_with_tools`, [ADR 0109](./wiki/decisions/0109-structured-output-beside-tools.md)). Worked example: `examples/structured_critic.yaml`. A leaf that holds the schema (`critic.yaml`) and plan-dispatch remain the choices when the answer should be a specialist's. |
-| `model_overrides` | agent | A prompt nuance for one provider: keyed by `gemini`, `anthropic`, `openai`, `xai`, `moonshot`, `deepseek` or `ollama`, each entry holds `instruction` (replaces the agent's instruction on that provider) or `instruction_append` (added after a blank line). The entry for the provider of the agent's `model` applies, before the skills index is appended; a `fallback_model` gets the primary's instruction. |
+| `model_overrides` | agent | A prompt nuance for one provider: keyed by `gemini`, `anthropic`, `openai`, `xai`, `moonshot`, `deepseek`, `typesafe` or `ollama`, each entry holds `instruction` (replaces the agent's instruction on that provider) or `instruction_append` (added after a blank line). The entry for the provider of the agent's `model` applies, before the skills index is appended; a `fallback_model` gets the primary's instruction. |
 | `tool_choice` | agent | Which tools the model may call: `auto` (the default), `none`, `required` (some tool), or `{ name: <tool> }` (that tool). A provider that rejects forcing sends a weaker choice and marks the span `llm.tool_choice.weakened` ([ADR 0117](./wiki/decisions/0117-tool-choice-and-effort-above-high-in-v2.md)). |
 | `generateContentConfig` / `outputSchema` | agent | The deprecated v1 spelling of `sampling`, `output.mime`, `reasoning` (as `thinkingConfig` / `reasoningEffort`), `tool_choice` (as `toolConfig.functionCallingConfig`) and `output.schema`. Both still load and behave the same; a load that finds either prints one deprecation line per file per process (`LoadSyndicateOptions.onWarning`, default `console.warn`), and a v2 key beside its v1 spelling on one agent is a load error. Only `toolConfig.functionCallingConfig.mode: VALIDATED` and Gemini's dynamic budget (`thinkingBudget: -1`) have no v2 form; `topK`, `seed`, the penalties, `candidateCount`, `safetySettings` and `includeThoughts` reach no provider, and the codemod drops `includeThoughts`. `npx melchizedek-codemod [--check] <file|dir>` rewrites a v1 file to v2, comments kept ([ADR 0115](./wiki/decisions/0115-yaml-schema-v2-provider-neutral-keys.md)). |
 | `yaml_reference` | subagent | Mount another syndicate file as a nested subagent. |
@@ -291,7 +291,8 @@ in `examples/specs/`.
 > dialect; every non-Gemini adapter normalizes them back to
 > standard lowercase JSON-Schema at request-build time
 > (`lib/models/schemaNormalize.ts`). MCP tools therefore work on any
-> provider's agents — Gemini, Claude, GPT, Grok, Kimi, or DeepSeek.
+> provider's agents — Gemini, Claude, GPT, Grok, Kimi, or DeepSeek (never
+> Jev, which calls no tool).
 
 ## 4. Sessions & long-term memory
 
@@ -413,8 +414,9 @@ accordingly — model optionality is a single YAML line per agent:
 | `grok-*` | xAI | `lib/models/grokAdapter.ts` (Responses API) | `XAI_API_KEY` | ✅ Agent Tools search |
 | `kimi-*` | Moonshot AI (Kimi) | `lib/models/kimiAdapter.ts` (chat completions) | `MOONSHOT_API_KEY` | ⚠ omitted + warning |
 | `deepseek-*` | DeepSeek | `lib/models/deepseekAdapter.ts` (chat completions) | `DEEPSEEK_API_KEY` | ⚠ omitted + warning |
+| `jev-*` | TypeSafe (Jev, a decision model) | `lib/models/jevAdapter.ts` (System One) | `TYPESAFE_API_KEY` | ✗ no tools at all |
 | `ollama/*` | Local Ollama | `lib/models/ollamaAdapter.ts` (chat completions) | none | ⚠ omitted + warning |
-| *any cloud id whose direct key is absent* | the id's own provider, via a gateway | `lib/models/gatewayAdapter.ts` (chat completions) | `MODEL_GATEWAY` + `MODEL_GATEWAY_API_KEY` | ⚠ omitted + reported |
+| *any cloud id whose direct key is absent, or every cloud id under `MODEL_GATEWAY_PREFER=gateway`* | the id's own provider, via a gateway | `lib/models/gatewayAdapter.ts` (chat completions; `jev-*` keeps `JevAdapter` on the gateway's System One route) | `MODEL_GATEWAY` + `MODEL_GATEWAY_API_KEY` | ◐ the gateway's own search (`MODEL_GATEWAY_SEARCH`) |
 
 The xAI adapter carries the deepest capability surface: `grok-4.5`
 requests pin `reasoning.effort: "medium"` (`lib/config.ts`), SSE
@@ -498,6 +500,102 @@ warning, `web_extract` works). Through `MODEL_GATEWAY` the ids go as
 capability matrix is asserted against the request body the adapter sends;
 it has not been run live.
 
+**TypeSafe (Jev).** `jev-*` ids route to `JevAdapter`
+(`lib/models/jevAdapter.ts`), against `https://api.typesafe.ai/v1/systemone`
+(`TYPESAFE_BASE_URL` for a proxy). Get a key at console.typesafe.ai/keys.
+Jev is a System One model, not a chat model: one request carries a `state`
+and typed `questions`, and the answer is one typed decision per question
+with calibrated probabilities, never prose, never a tool call, in about a
+tenth of a second at $0.042 per million input tokens and nothing for output
+(migration 0022). The engine makes it the model of a classifier agent: the
+agent's `output.schema` becomes the questions (`lib/models/jev.ts`
+`questionsFromSchema`: a boolean property is a yes/no `noul` question, a
+string with `enum` or a `oneOf` of described constants is a `choice`, an
+integer whose `oneOf` describes the levels 0..n-1 in order is a `score`;
+the property's `description` is the question), the instruction and the
+conversation's text are the state, and the final is the schema's object
+with the raw answers under a reserved `jev` key, so code acts on
+confidence. The ids are `jev-latest` (the default, TypeSafe's alias for the
+newest stable release), `jev-preview`, `jev-1.14.0` and `jev-1.13.0`
+(`GET /v1/models` lists them); 64k tokens per request, 32k per question.
+What works: structured output, direct or through either gateway (Vercel AI
+Gateway's `/typesafe/v1/systemone` as `typesafe-ai/jev`, OpenRouter's
+`/api/v1/systemone` as `typesafe/jev-1.14`, `MODEL_GATEWAY_MODEL_MAP` for
+either). What does not, by the nature of the model: tools and delegation
+(dropped; the doctor names an agent with tools on a Jev id as a gap),
+`reasoning:`, streaming (the final is the only response), images (dropped)
+and native search. An agent with no `output.schema`, or with a property Jev
+cannot decide (a free string, an array, a nested object), fails before any
+call with `TYPESAFE_SCHEMA_REQUIRED` or `TYPESAFE_SCHEMA_UNSUPPORTED`,
+naming the property and the shapes Jev takes. `examples/classifier.yaml`
+is the pattern, and `decide()` from `melchizedek-agents/model` is the same
+call from code, typed on its questions (`noul`, `choice`, `score`). The
+row in the capability matrix is asserted against the request body the
+adapter sends; the classifier and all four ids were run live through
+Vercel AI Gateway on 2026-10-23 (answers in 150 to 715 ms); TypeSafe's own
+API and OpenRouter's route were not.
+
+**Which path wins.** By default a provider's own key wins for its
+provider and the gateway serves only what has no key (ADR 0012).
+`MODEL_GATEWAY_PREFER=gateway` turns that round: every cloud id goes
+through the configured gateway even beside a direct key, one bill and one
+dashboard, at the gateway's fidelity (no native search). `MODEL_GATEWAY_EXCEPT`
+is a comma list of provider ids that take the opposite of the preference
+either way: `gemini` under `prefer=gateway` keeps Gemini on its own key for
+grounding; `xai` under the default sends Grok through the gateway while
+everything else stays direct. Two things never move: `ollama/*` is always
+direct, and an A2A caller's own key (BYOK) funds its provider directly. A
+preference whose path is not funded falls back to the other; an unknown
+preference word or a provider name the list does not know is named by the
+doctor (ADR 0145). Both variables are read through the credential source,
+like the key.
+
+**What a gateway gives back** (ADR 0146). An agent's `web_search` (or
+`google_search`) is not dropped on the gateway path: it runs as the
+gateway's own search, on any model. Vercel AI Gateway runs a server tool
+(`vercel:exa_search` by default; `MODEL_GATEWAY_SEARCH` picks `exa`,
+`perplexity`, `parallel`, `browserbase` or `tako`): the gateway searches,
+folds the results into the model's context and answers in the same
+response, the span counts the calls, and no citations come back. OpenRouter
+runs its web plugin, which is the provider's native search where the model
+has one (OpenAI, Anthropic, Google, xAI) and Exa elsewhere
+(`MODEL_GATEWAY_SEARCH` picks `native`, `exa`, `firecrawl`, `parallel` or
+`perplexity`), and returns `url_citation` annotations the adapter keeps as
+the final's `grounding.citations`. `MODEL_GATEWAY_SEARCH=off` drops the tool
+as before. `MODEL_GATEWAY_SEARCH_RESULTS` (default 3) is passed as each
+engine's count, Exa on its instant type and Perplexity under a cap of
+2,000 tokens a result (ADR 0148), because the gateway folds the results into
+the prompt as input tokens: measured live, Exa at three results carried
+7,000 to 17,600 prompt tokens for a one-line question (unbounded, 13,000 to
+20,000), Perplexity at three 6,200. Each gateway also bills its search on
+top of the tokens (Exa about $0.007 a request on OpenRouter; Vercel prices
+its engines). A gateway is for billing and breadth, not for grounding: for a
+search-heavy agent, keep the provider that does the searching on its own key
+(its native search and citations) and let the gateway serve the rest, which
+a direct key beside the gateway key does by default and
+`MODEL_GATEWAY_EXCEPT` keeps under `MODEL_GATEWAY_PREFER=gateway`. xAI's `x_search`
+and `collections_search` have no gateway form and are dropped. Long-term
+memory's embedder follows the same rule: with no key for the embedding
+provider, or under `MODEL_GATEWAY_PREFER=gateway`, it embeds through the
+gateway's `/embeddings` when the gateway carries the same model (Vercel
+carries `google/gemini-embedding-001` and `openai/text-embedding-3-small`
+and honours `dimensions`, checked live at 768; OpenRouter carries OpenAI's
+only), so a store embedded directly and one embedded through the gateway
+hold the same vectors; a gateway that lacks the model changes nothing.
+OpenRouter carries no Gemini embedding model, so with no Gemini key the
+documented answer there is `MEMORY_EMBEDDING_PROVIDER=openai`
+(`text-embedding-3-small` at 768, a tenth of Gemini's price), with one
+caveat the store now enforces (migration 0023, ADR 0147): a memory store
+records the provider, model and dimension its vectors come from on its
+first write and refuses a different model at start, since two models'
+vectors do not compare even at the same size; switching means re-embedding
+every stored fact, which `npm run memory -- reembed` does (a dry run first;
+`--yes` writes): with `MEMORY_EMBEDDING_*` set to the new embedder it walks
+the facts in id order, writes each page's vectors back and records the new
+model last, under an advisory lock on `DATABASE_URL`, so an interrupted run
+leaves the old record in place (ADR 0148). `npm run doctor` prints a
+`memory` line saying what would embed here, or what to set.
+
 **Which keys do I need?** `npm run doctor` (the `melchizedek-doctor` bin)
 reads every syndicate YAML, resolves each agent's model under your `.env`,
 and prints one table — agent, model, provider, which declared server-side
@@ -626,7 +724,9 @@ in a `FallbackAdapter`.
 `melchizedek-agents/model` is the model layer on its own (ADR 0068): the
 contract's types,
 `ClaudeAdapter`, `GptAdapter`, `GrokAdapter`, `KimiAdapter`, `DeepSeekAdapter`,
-`OllamaAdapter`, `GatewayAdapter`, `GeminiAdapter`, the
+`JevAdapter` (with `decide`, `noul`, `choice`, `score`, `questionsFromSchema`
+and `objectFromAnswers` beside it), `OllamaAdapter`, `GatewayAdapter`,
+`GeminiAdapter`, the
 `ChatCompletionsAdapter` base, `resolveAdapter`,
 `resolveAdapterWithFallback`, `FallbackAdapter` and the circuit breaker's
 helpers. A project that only calls models imports from there. Its
@@ -698,7 +798,8 @@ calls), and `syndicate.usage` carries `cache_read` / `cache_write` per
 model. `model_pricing.cache_read_per_mtok` / `cache_write_per_mtok` price
 them (migration 0017; NULL prices them as input), seeded for Anthropic and
 OpenAI from their price lists (ADR 0139). Migration 0019 adds DeepSeek (at
-its peak rate) and Moonshot Kimi rows.
+its peak rate) and Moonshot Kimi rows; 0022 adds TypeSafe Jev (input only,
+output free).
 Operate it with `npm run telemetry:stats`,
 `telemetry:prune` and `telemetry:replay` (the exporter spools failed
 batches to `outputs/telemetry-deadletter.ndjson`).
@@ -880,7 +981,7 @@ names; nothing is kept by the framework anywhere else.
 | The prompt: the user's message, the conversation, tool results | The model provider of each agent that runs (the model-id prefix) | The provider's policy | The `model:` lines in the YAML; `ollama/` ids stay on your machine |
 | Tool calls (`web_search`, `web_extract`, OpenAPI, MCP) | The tool's own host | That host's policy | The agent's `tools:`, `openapi:`, `mcp_server_url` / `mcp_tools` |
 | Sessions (conversation history) | Your Postgres, `adk_sessions` | 7 days after the last message | `ttlDays` (`postgresStorage`) |
-| Long-term memory facts | Your Postgres, `adk_memory_facts`; **the transcript is also sent to the extraction and embedding providers, Gemini by default whatever the agents run on** (the server warns at boot when they differ) | Until erased, or `memory_retention_days` | `MEMORY_EXTRACTION_MODEL`, `MEMORY_EMBEDDING_PROVIDER`, `memory_retention_days` |
+| Long-term memory facts | Your Postgres, `adk_memory_facts`; **the transcript is also sent to the extraction and embedding providers, Gemini by default whatever the agents run on** (the server warns at boot when they differ; through the gateway when it carries the embedding model, ADR 0146) | Until erased, or `memory_retention_days` | `MEMORY_EXTRACTION_MODEL`, `MEMORY_EMBEDDING_PROVIDER`, `memory_retention_days` |
 | The ledger: each turn's input, output and tool results (key-shaped secrets redacted) | Your Postgres, `adk_turns`, `adk_telemetry` | **Until you prune it**: schedule `melchizedek_prune_telemetry(<days>)` | `TELEMETRY_REDACT`, the prune's `turn_days` |
 | Sampled full model requests | Your Postgres, `adk_payloads` | 30 days | `TELEMETRY_PAYLOADS`, `TELEMETRY_PAYLOAD_TTL_DAYS` |
 | Traces, when `OTEL_EXPORTER_OTLP_ENDPOINT` is set | Your OTLP collector, conversation content included with key-shaped secrets redacted (`off` drops it) | Your collector's policy | `OTEL_EXPORT_CONTENT` (`redacted`, `off`, `raw`) |
@@ -1680,7 +1781,7 @@ the canonical minimal block on the engine's model contract:
 `resolveAdapter(modelId)` from `melchizedek-agents/model`, then
 `adapter.generate({ model, system, messages, stream })`, reading partial
 and final responses. The id's prefix picks the provider (`gemini-*`,
-`claude-*`, `gpt-*`, `grok-*`, `kimi-*`, `deepseek-*`, `ollama/*`), the key comes from
+`claude-*`, `gpt-*`, `grok-*`, `kimi-*`, `deepseek-*`, `jev-*`, `ollama/*`), the key comes from
 the environment. A turn
 with tools, sessions and telemetry is `runSyndicateTurn`.
 

package/ONBOARDING.md

@@ -9,7 +9,7 @@ In a clone, the commands are spelled as npm scripts (`npm run doctor`, `npm run
 | # | You have | Guide |
 |---|---|---|
 | 1 | Nothing yet: run open-weight models locally (Ollama, no key) | `--level local` |
-| 2 | One provider's API key (Gemini, Anthropic, OpenAI, xAI, Moonshot or DeepSeek) | `--level one-provider` |
+| 2 | One provider's API key (Gemini, Anthropic, OpenAI, xAI, Moonshot, DeepSeek or TypeSafe) | `--level one-provider` |
 | 3 | API keys for several providers | `--level several-providers` |
 | 4 | One gateway key (Vercel AI Gateway or OpenRouter) | `--level gateway` |
 | 5 | Cloud platform credentials (Vertex AI, Amazon Bedrock, Azure OpenAI) | `--level cloud-platform` |
@@ -63,17 +63,19 @@ The model id's prefix picks the provider, and that provider's key funds it. One
 | `XAI_API_KEY` | an API key from https://console.x.ai | xAI Grok: model ids grok-* |
 | `MOONSHOT_API_KEY` | an API key from https://platform.moonshot.ai | Moonshot Kimi: model ids kimi-* |
 | `DEEPSEEK_API_KEY` | an API key from https://platform.deepseek.com/api_keys | DeepSeek: model ids deepseek-* |
+| `TYPESAFE_API_KEY` | an API key from https://console.typesafe.ai/keys | TypeSafe Jev: model ids jev-* (a decision model: it answers an output.schema, never prose) |
 
 **Confirm:** `npx melchizedek-doctor`: the providers line shows a ✓ beside your provider, and the files of that tier read `ready`.
 
 **Runs at this level:**
 
-- GOOGLE_GENAI_API_KEY: account_memory (template), case_desk (template), draft_review (template), intake_extractor (template), research_brief (template), research_desk (template), review_panel (template), support_triage (template), systems_operator (template), ares (example), cartographers (example), connectors (example), critic (example), current_events (example), delegation (example), harness (example), hierarchical (example), image_production (example), librarian (example), patient_advocate (example), pipeline (example), research (example), scribe (example), scriptorium (example), style_council (example), syndicate (example), weather (example)
+- GOOGLE_GENAI_API_KEY: account_memory (template), case_desk (template), draft_review (template), intake_extractor (template), prompt_writer (template), research_brief (template), research_desk (template), review_panel (template), support_triage (template), systems_operator (template), ares (example), cartographers (example), connectors (example), critic (example), current_events (example), delegation (example), harness (example), hierarchical (example), image_production (example), librarian (example), patient_advocate (example), pipeline (example), research (example), scribe (example), scriptorium (example), style_council (example), syndicate (example), weather (example)
 - ANTHROPIC_API_KEY: claude (example), structured_critic (example)
 - OPENAI_API_KEY: no shipped file yet (change a `model:` line to use one)
 - XAI_API_KEY: no shipped file yet (change a `model:` line to use one)
 - MOONSHOT_API_KEY: no shipped file yet (change a `model:` line to use one)
 - DEEPSEEK_API_KEY: no shipped file yet (change a `model:` line to use one)
+- TYPESAFE_API_KEY: classifier (example)
 - with no key at all: conversational (template), assistant (example), council (example), event_assistant (example), tutor (example)
 
 **First commands:**
@@ -104,6 +106,7 @@ Each key funds its own provider, and a syndicate may mix them: one agent on Clau
 | `XAI_API_KEY` | an API key from https://console.x.ai | xAI Grok: model ids grok-* |
 | `MOONSHOT_API_KEY` | an API key from https://platform.moonshot.ai | Moonshot Kimi: model ids kimi-* |
 | `DEEPSEEK_API_KEY` | an API key from https://platform.deepseek.com/api_keys | DeepSeek: model ids deepseek-* |
+| `TYPESAFE_API_KEY` | an API key from https://console.typesafe.ai/keys | TypeSafe Jev: model ids jev-* (a decision model: it answers an output.schema, never prose) |
 
 **Confirm:** `npx melchizedek-doctor`: a ✓ beside each provider you set; `multi-provider` files read `ready` once every provider they use has its key.
 
@@ -127,7 +130,7 @@ npx melchizedek-chat --syndicate model_zoo
 
 ## 4. A gateway key
 
-One key serves every cloud model id whose direct key is absent, through the gateway's OpenAI-compatible endpoint. It is a fallback, never a preempt: a direct key always wins for its provider. Ollama never goes through it.
+One key serves every cloud model id whose direct key is absent, through the gateway's OpenAI-compatible endpoint (and TypeSafe Jev on its System One route). By default it is a fallback: a direct key wins for its provider; MODEL_GATEWAY_PREFER=gateway turns that round, and MODEL_GATEWAY_EXCEPT names the providers that take the opposite. Ollama never goes through it.
 
 **Set in `.env`** (names and shapes only; you type the values yourself):
 
@@ -137,12 +140,14 @@ One key serves every cloud model id whose direct key is absent, through the gate
 | `MODEL_GATEWAY_API_KEY` | the gateway key (https://vercel.com/ai-gateway or https://openrouter.ai/keys) | funds every id with no direct key |
 | `MODEL_GATEWAY_BASE_URL` | https URL | optional: a self-hosted proxy speaking the same dialect (LiteLLM) |
 | `MODEL_GATEWAY_MODEL_MAP` | yaml-id=gateway-id,yaml-id=gateway-id | optional: fix an id the default mapping gets wrong |
+| `MODEL_GATEWAY_PREFER` | direct | gateway | optional: gateway sends every cloud id through the gateway even beside a direct key (one bill); direct, the default, lets each provider's own key win |
+| `MODEL_GATEWAY_EXCEPT` | gemini,xai | optional: providers that take the opposite of the preference (never ollama) |
 
 **Confirm:** `npx melchizedek-doctor`: a `gateway` line with no ✗, and providers without a direct key marked `◇ via gateway`.
 
 **Runs at this level:**
 
-- every cloud file: account_memory (template), case_desk (template), draft_review (template), intake_extractor (template), research_brief (template), research_desk (template), review_panel (template), support_triage (template), systems_operator (template), ares (example), cartographers (example), connectors (example), critic (example), current_events (example), delegation (example), harness (example), hierarchical (example), image_production (example), librarian (example), patient_advocate (example), pipeline (example), research (example), scribe (example), scriptorium (example), style_council (example), syndicate (example), weather (example), claude (example), structured_critic (example), model_zoo (example)
+- every cloud file: account_memory (template), case_desk (template), draft_review (template), intake_extractor (template), prompt_writer (template), research_brief (template), research_desk (template), review_panel (template), support_triage (template), systems_operator (template), ares (example), cartographers (example), connectors (example), critic (example), current_events (example), delegation (example), harness (example), hierarchical (example), image_production (example), librarian (example), patient_advocate (example), pipeline (example), research (example), scribe (example), scriptorium (example), style_council (example), syndicate (example), weather (example), claude (example), structured_critic (example), classifier (example), model_zoo (example)
 
 **First commands:**
 
@@ -153,8 +158,9 @@ npx melchizedek-chat --syndicate research_brief
 
 **Notes:**
 
-- Native search is lost on the gateway path (Gemini grounding, Anthropic and OpenAI web_search, xAI x_search); the doctor marks each dropped tool.
-- Long-term memory embeds through Gemini by default, which the gateway does not serve: set GOOGLE_GENAI_API_KEY, or MEMORY_EMBEDDING_PROVIDER=openai or ollama.
+- web_search runs as the gateway's own search on the gateway path (Vercel's exa_search server tool; OpenRouter's web plugin, the provider's native search where it has one, with citations); MODEL_GATEWAY_SEARCH names the engine or turns it off, MODEL_GATEWAY_SEARCH_RESULTS (default 3) bounds what it folds into the prompt, and xAI's x_search and Collections are dropped; the doctor marks each.
+- A gateway is for billing and breadth, not for grounding: for a search-heavy agent, keep the provider that does the searching on its own key (its native search, citations and all) and let the gateway serve the rest; a direct key beside the gateway key does that by default, and MODEL_GATEWAY_EXCEPT keeps it so under MODEL_GATEWAY_PREFER=gateway.
+- Long-term memory embeds through the gateway when it carries the same embedding model (Vercel carries google/gemini-embedding-001). OpenRouter has no Gemini one: set GOOGLE_GENAI_API_KEY, or MEMORY_EMBEDDING_PROVIDER=openai to embed text-embedding-3-small at 768 through it; a store already embedded with Gemini must be re-embedded if the model changes, and the store refuses a different model at start (the doctor's memory line says what would embed).
 
 **Onboarding skill:** `melchizedek-onboard-keys` (`npx melchizedek-setup --level gateway` prints this guide)
 
@@ -182,7 +188,7 @@ The model id still picks the provider; these variables pick the cloud it is reac
 
 **Runs at this level:**
 
-- Gemini on Vertex AI: account_memory (template), case_desk (template), draft_review (template), intake_extractor (template), research_brief (template), research_desk (template), review_panel (template), support_triage (template), systems_operator (template), ares (example), cartographers (example), connectors (example), critic (example), current_events (example), delegation (example), harness (example), hierarchical (example), image_production (example), librarian (example), patient_advocate (example), pipeline (example), research (example), scribe (example), scriptorium (example), style_council (example), syndicate (example), weather (example)
+- Gemini on Vertex AI: account_memory (template), case_desk (template), draft_review (template), intake_extractor (template), prompt_writer (template), research_brief (template), research_desk (template), review_panel (template), support_triage (template), systems_operator (template), ares (example), cartographers (example), connectors (example), critic (example), current_events (example), delegation (example), harness (example), hierarchical (example), image_production (example), librarian (example), patient_advocate (example), pipeline (example), research (example), scribe (example), scriptorium (example), style_council (example), syndicate (example), weather (example)
 - Claude on Bedrock or Vertex AI: claude (example), structured_critic (example)
 - GPT on Azure OpenAI: no shipped file yet (change a `model:` line to use one)
 
@@ -215,7 +221,7 @@ The A2A server lets each caller fund its own inference: the caller sends its key
 
 **Runs at this level:**
 
-- any file; start from a template: account_memory, case_desk, conversational, draft_review, intake_extractor, research_brief, research_desk, review_panel, support_triage, systems_operator
+- any file; start from a template: account_memory, case_desk, conversational, draft_review, intake_extractor, prompt_writer, research_brief, research_desk, review_panel, support_triage, systems_operator
 
 **First commands:**
 
@@ -254,7 +260,7 @@ A2A_AUTH decides who a caller is, and so whose data a request touches. `callers`
 
 **Runs at this level:**
 
-- any file; start from a template: account_memory, case_desk, conversational, draft_review, intake_extractor, research_brief, research_desk, review_panel, support_triage, systems_operator
+- any file; start from a template: account_memory, case_desk, conversational, draft_review, intake_extractor, prompt_writer, research_brief, research_desk, review_panel, support_triage, systems_operator
 
 **First commands:**
 

package/QUICKSTART.md

@@ -24,8 +24,9 @@ are the two most common paths spelled out.
 - Optional: **Ollama** ([ollama.com](https://ollama.com)) for the
   open-weight local syndicates; provider keys only for the models you
   actually declare — **Anthropic** (`claude-*`), **OpenAI** (`gpt-*`),
-  **xAI** (`grok-*`), **Moonshot** (`kimi-*`), **DeepSeek** (`deepseek-*`) — or one `MODEL_GATEWAY` key as the fallback for
-  whatever direct key is missing (native search is lost on that path);
+  **xAI** (`grok-*`), **Moonshot** (`kimi-*`), **DeepSeek** (`deepseek-*`), **TypeSafe** (`jev-*`, a decision model) — or one
+  `MODEL_GATEWAY` key (Vercel AI Gateway or OpenRouter) that serves every cloud id whose direct key is missing, Jev included
+  (web search then runs as the gateway's own search; x_search is lost on that path);
   and a free **Supabase project** (only for persistent sessions / memory).
   Not sure which you need? `npm run doctor` tells you, read-only.
 
@@ -260,7 +261,8 @@ console.log(result.text);
 |---|---|
 | `Gemini API Key is not configured` | `.env` missing or key not set — step 2. |
 | `[400] Tool call context circulation is not enabled` | The agent's `model:` is too old for agent transfer. Use `gemini-3.8-flash` or newer (all shipped configs already do). |
-| `Model not found` for `claude-*` / `gpt-*` / `grok-*` / `kimi-*` / `deepseek-*` | The matching provider key (`ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `XAI_API_KEY` / `MOONSHOT_API_KEY` / `DEEPSEEK_API_KEY`) is not set in `.env`, so the provider wasn't registered — `npm run doctor` names the variable. Or set `MODEL_GATEWAY` + `MODEL_GATEWAY_API_KEY` once for every cloud provider (native search is lost on that path). |
+| `Model not found` for `claude-*` / `gpt-*` / `grok-*` / `kimi-*` / `deepseek-*` / `jev-*` | The matching provider key (`ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `XAI_API_KEY` / `MOONSHOT_API_KEY` / `DEEPSEEK_API_KEY` / `TYPESAFE_API_KEY`) is not set in `.env`, so the provider wasn't registered — `npm run doctor` names the variable. Or set `MODEL_GATEWAY` + `MODEL_GATEWAY_API_KEY` once for every cloud provider (web search then runs as the gateway's own). |
+| `TYPESAFE_SCHEMA_REQUIRED` / `TYPESAFE_SCHEMA_UNSUPPORTED` | A `jev-*` agent has no `output.schema`, or one of its properties is not a decision Jev can make. Give every property a decision shape: a boolean, a string with `enum` or a `oneOf` of described constants, or an integer whose `oneOf` describes the levels 0..n-1; the error names the property. `examples/classifier.yaml` is the pattern. |
 | `GATEWAY_HTTP_ERROR … 404/400` | The gateway rejected the mapped model id. Fix the name once in `.env`: `MODEL_GATEWAY_MODEL_MAP=<your id>=<the gateway's id>`. `GATEWAY_KEY_MISSING` means `MODEL_GATEWAY` is set without `MODEL_GATEWAY_API_KEY`. |
 | `OLLAMA_UNREACHABLE` for `ollama/*` | Ollama isn't running — start the app or `ollama serve`; then check the model is pulled (`ollama list`). |
 | `Refusing to connect to private/loopback MCP host` | The SSRF guard is on (correctly). For the local demo set `ALLOW_PRIVATE_MCP=true` in `.env`. |

package/README.md

@@ -2,7 +2,7 @@
 
 A multi-model, multi-agent orchestration framework with its own agent loop, model contract, tools, sessions and workflow engine. Agent hierarchies, prompts, models, tools, and delegation rules are declared in YAML files called **Syndicates**; the engine in `lib/` runs whatever you put in `config/agents/`.
 
-Gemini, Claude, GPT, Grok, Kimi, and DeepSeek each run on the engine's own adapter for their provider's API, and open-weight models run locally through Ollama with no API key. A subagent can also pick up tools at runtime from a Model Context Protocol (MCP) server.
+Gemini, Claude, GPT, Grok, Kimi, and DeepSeek each run on the engine's own adapter for their provider's API, TypeSafe's Jev answers a classifier's schema as calibrated decisions, and open-weight models run locally through Ollama with no API key. One Vercel AI Gateway or OpenRouter key serves every cloud model you have no direct key for. A subagent can also pick up tools at runtime from a Model Context Protocol (MCP) server.
 
 > Companion repository for the curriculum at [lyceumagents.com/curriculum](https://lyceumagents.com/curriculum/). The framework works standalone or alongside the course.
 
@@ -11,7 +11,7 @@ Gemini, Claude, GPT, Grok, Kimi, and DeepSeek each run on the engine's own adapt
 ## Features
 
 - **Declarative YAML configuration** — Orchestrators, subagents, routing, output schemas, and tool assignments in one readable document. Tools and guards are registered in code; YAML names them.
-- **Multi-model routing** — Mix providers within the same agent graph (`gemini-*`, `claude-*`, `gpt-*`, `grok-*`, `kimi-*`, `deepseek-*`, and local `ollama/*`). Switching an agent's model is a one-line change.
+- **Multi-model routing** — Mix providers within the same agent graph (`gemini-*`, `claude-*`, `gpt-*`, `grok-*`, `kimi-*`, `deepseek-*`, `jev-*`, and local `ollama/*`). Switching an agent's model is a one-line change, and one gateway key (`MODEL_GATEWAY`) stands in for every direct key you have not set.
 - **MCP integration** — Give an agent an `mcp_server_url:`, or several servers under `mcp_servers:`, and their tools are discovered over Streamable HTTP (or legacy SSE) and wrapped as agent tools at runtime. URLs are SSRF-guarded; an OAuth server with no pre-issued client is discovered and registered at, within the operator's host allowlist. In the other direction, `melchizedek-mcp` serves your syndicates as MCP tools to Claude Code, Codex and other MCP clients.
 - **Persistent sessions & long-term memory** — Optional Supabase backend for session persistence and pgvector memory: transcripts are distilled into structured records and recalled by similarity in later sessions. Without it, sessions run in memory.
 - **Native tools** — Web search, image generation, and a blind image-inventory tool that accepts only a file path, so the expected result can never reach the observer.
@@ -50,13 +50,15 @@ npm run syndicate:council
 
 ### 2. Cloud models
 
+The quickest way to every cloud model is one gateway key: set `MODEL_GATEWAY=vercel` (or `openrouter`) and `MODEL_GATEWAY_API_KEY` in `.env`, and every shipped syndicate runs, billed to that one account (web search runs as the gateway's own search, and xAI's x_search is the one tool a gateway cannot run; a direct key set beside it wins for its provider by default, and `MODEL_GATEWAY_PREFER=gateway` turns that round, with `MODEL_GATEWAY_EXCEPT` for the providers that take the opposite). Or bring the providers' own keys:
+
 ```bash
 cp .env.example .env    # add GOOGLE_GENAI_API_KEY (free from Google AI Studio)
 npm run chat:syndicate  # interactive REPL with the default syndicate (Gemini)
 npm run doctor          # shows which syndicates your current keys unlock
 ```
 
-Other providers are optional: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `XAI_API_KEY`, `MOONSHOT_API_KEY`, and `DEEPSEEK_API_KEY` unlock the syndicates that use them (for example `npm run syndicate:claude`).
+Other providers are optional: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `XAI_API_KEY`, `MOONSHOT_API_KEY`, `DEEPSEEK_API_KEY` and `TYPESAFE_API_KEY` unlock the syndicates that use them (for example `npm run syndicate:claude`, or `npm run syndicate:classifier` for the Jev decision model).
 
 Test the providers you have keys for:
 
@@ -199,6 +201,7 @@ Configurations live in `config/agents/examples/` and each demonstrates a differe
 | `council.yaml` | Advocate/skeptic council weighed by an orchestrator (local) | [1.05 · Workflows & Voice](https://lyceumagents.com/curriculum/workflows-and-voice/) |
 | `critic.yaml` | Drafter → Critic loop that re-drafts until a parsed confidence score clears the bar | [1.04 · Testing & Refinement](https://lyceumagents.com/curriculum/testing-and-refinement/) |
 | `structured_critic.yaml` | The critic as one agent: it delegates to a Drafter, then answers in its own JSON schema (Claude) | — |
+| `classifier.yaml` | A support-triage classifier on TypeSafe's Jev: the output schema is the questions, the answer is typed decisions with calibrated probabilities | — |
 | `delegation.yaml` | Intent routing to specialists via agent descriptions | [1.05 · Workflows & Voice](https://lyceumagents.com/curriculum/workflows-and-voice/) |
 | `hierarchical.yaml` | Goal decomposition into sequential research and writing stages, then a checked merge | [1.05 · Workflows & Voice](https://lyceumagents.com/curriculum/workflows-and-voice/) |
 | `style_council.yaml` | Three stylists with identical knowledge and different voices, behind one router | [1.05 · Workflows & Voice](https://lyceumagents.com/curriculum/workflows-and-voice/) |
@@ -209,7 +212,7 @@ Configurations live in `config/agents/examples/` and each demonstrates a differe
 | `image_production.yaml` | Spec-first image generation, a blind inventory, and a separate spec auditor | [2.04 · Multimodal Agents](https://lyceumagents.com/curriculum/multimodal-agents/) |
 | `current_events.yaml` | Current-event aggregation and fact-checking: an X researcher and a web researcher report to a tool-free arbiter | [2.05 · Fact-Checking Arbiter](https://lyceumagents.com/curriculum/fact-checking-agent/) |
 | `claude.yaml` | Minimal configuration using the Anthropic adapter | — |
-| `model_zoo.yaml` | One agent per provider (Qwen, Claude, Grok, GPT, Gemini, Kimi, DeepSeek) | — |
+| `model_zoo.yaml` | One agent per chat provider (Qwen, Claude, Grok, GPT, Gemini, Kimi, DeepSeek); Jev, a decision model, has `classifier.yaml` | — |
 | `research.yaml` | Plan-and-dispatch over keyless clinical and literature sources, with an identifier and retraction guard | — |
 | `scriptorium.yaml` | Agents over the `wiki/` bundle: answer with citations, author through a validated save gate | — |
 | `cartographers.yaml` | Agents that record the judgments in the wiki's prose as graph relations | — |