melchizedek-agents 1.1.0 → 1.3.0

package/skills/README.md

@@ -2,7 +2,7 @@
 
 ## What this is
 
-This directory contains a suite of six Agent Skills built to the open SKILL.md standard: one directory per skill, a SKILL.md file with `name` and `description` frontmatter, and optional supporting files. The skills teach a coding agent how to find, run, author, serve, remember with, and write with Melchizedek syndicates. They ship in the npm package melchizedek-agents and in the public repository, inside `skills/`.
+This directory contains a suite of eleven Agent Skills built to the open SKILL.md standard: one directory per skill, a SKILL.md file with `name` and `description` frontmatter, and optional supporting files. The skills teach a coding agent how to onboard a person from the credentials they have, and how to find, run, author, serve, remember with, and write with Melchizedek syndicates. They ship in the npm package melchizedek-agents and in the public repository, inside `skills/`.
 
 ## The skills
 
@@ -13,6 +13,14 @@ This directory contains a suite of six Agent Skills built to the open SKILL.md s
 - `melchizedek-models`: Teaches model ids and providers, keys, keyless Ollama, the gateway fallback, per-agent settings, and the errors.
 - `melchizedek-scribe`: Teaches writing documents from a brief with the Scribe syndicate.
 
+Five onboarding skills route a person by what they have and walk the startup guide for it (`npx melchizedek-setup --level <id>` prints each guide):
+
+- `melchizedek-onboard`: The triage. Asks what the person has and routes to one of ten authentication levels and the skill below that owns it.
+- `melchizedek-onboard-local`: No key: Ollama and the keyless syndicates.
+- `melchizedek-onboard-keys`: One provider's key, several, a gateway key, Sign in with ChatGPT on the person's own machine, and the honest answer for a Codex, Claude.ai or Gemini CLI sign-in.
+- `melchizedek-onboard-cloud`: Vertex AI, Amazon Bedrock and Azure OpenAI credentials.
+- `melchizedek-onboard-serve`: Serving to others: per-caller keys (BYOK), caller identities (`A2A_AUTH`), and OAuth tool grants.
+
 ## Install
 
 Install the skills using any of three methods.
@@ -37,6 +45,7 @@ The command accepts these flags:
 - `--only <names>` installs a subset.
 - `--force` overwrites a file that differs.
 - `--dry-run` prints without writing.
+- `--agents-md` also writes a pointer block into the project's `AGENTS.md` (created when absent; only the block between its markers is ever rewritten).
 
 You can inspect target paths and available skills:
 
@@ -69,6 +78,6 @@ Install by hand by copying any `skills/<name>/` directory into a target location
 
 ## How the prose was written
 
-The Scribe syndicate (`config/agents/examples/scribe.yaml`, a Gemini agent that writes a document from a technical brief and audits it against the brief) wrote each SKILL.md body from one brief per skill. A person then reviewed each file. The briefs carry the facts; the Scribe carries the voice. To change a skill, change the facts and rerun with the melchizedek-scribe skill.
+The five onboarding skills are short procedures written by hand: they print their facts from `melchizedek-setup` instead of restating them, so the facts live in one place (`lib/onboarding.ts`). The Scribe syndicate (`config/agents/examples/scribe.yaml`, a Gemini agent that writes a document from a technical brief and audits it against the brief) wrote every other SKILL.md body from one brief per skill. A person then reviewed each file. The briefs carry the facts; the Scribe carries the voice. To change a skill, change the facts and rerun with the melchizedek-scribe skill.
 
 The suite shares the MIT license of the package.

package/skills/briefs/_shared.md

@@ -5,7 +5,7 @@ SHARED FACTS (true for every document in this series; use those the section need
 - The loader reads syndicate files from `<cwd>/config/agents/` by default. A bare name (`tutor`) resolves to `config/agents/tutor.yaml` at the root first, then `config/agents/examples/tutor.yaml`. The environment variable MELCHIZEDEK_AGENTS_DIR, or `loadSyndicate(file, { agentsDir })` in code, points the loader at another directory; the loader refuses any path outside that directory.
 - The starter pack: nineteen example syndicates ship in the package at `node_modules/melchizedek-agents/config/agents/examples/` (in a clone: `config/agents/examples/`), beside `syndicateSchema.yaml`, the annotated reference for every field. Every example opens with a `# tier:` comment line: `keyless` (every agent is an ollama/* model), a single provider such as `gemini` or `anthropic`, or `multi-provider`.
 - Keys live in a `.env` file at the working directory; real environment variables win over the file. The Gemini key is GOOGLE_GENAI_API_KEY. No key value is ever printed by any framework command.
-- This document is one of six in the melchizedek skills suite (the others: melchizedek, melchizedek-author, melchizedek-serve, melchizedek-memory, melchizedek-models, melchizedek-scribe). Refer a reader to a sibling by its name when a topic belongs there; do not repeat the sibling's content.
+- This document is one of the Scribe-written skills in the melchizedek suite (the six: melchizedek, melchizedek-author, melchizedek-serve, melchizedek-memory, melchizedek-models, melchizedek-scribe; five hand-written onboarding skills, melchizedek-onboard and its four level skills, sit beside them). Refer a reader to a sibling by its name when a topic belongs there; do not repeat the sibling's content.
 - The reader of a skill file is a coding agent (Claude Code, Codex, Cursor, OpenCode, Gemini CLI) acting for a software engineer. It reads the file when the task matches the description, then acts. Every command it might run goes in a fenced bash block, with the exact flags. Prose between commands says when to run which and what the output means. Nothing decorative.
 
 GLOBAL LIMITS FOR SKILL FILES:

package/skills/briefs/melchizedek-models.md

@@ -32,12 +32,14 @@ One key for every cloud provider (the gateway fallback):
 - Dials: `MODEL_GATEWAY_MODEL_MAP=<your id>=<the gateway's id>` renames an id the gateway rejects; `MODEL_GATEWAY_BASE_URL` points at a self-hosted proxy.
 - Telemetry attributes the call to the upstream provider and records the transport separately.
 Settings per agent:
-- `reasoning:` on the agent block, beside `model:`, sets how hard the agent reasons: `none`, `low`, `medium`, `high`, or `{ budget_tokens: 4096 }`. It reads the same on every provider; unset keeps the provider's default. The compiler sends each provider the field it reads: Gemini 3 and later get a thinking level (`none` is `MINIMAL`, then `LOW`, `MEDIUM`, `HIGH`); Gemini 2.x, and Claude 4.6 or older, get a thinking budget of 0, 2048, 8192 or 16384 tokens; every later Claude model gets adaptive thinking at an effort of `low`, `medium` or `high`, and `none` is that model's own off switch, sent at `low` effort; every other provider, and the gateway, gets an effort word, and where the provider lacks that word, its nearest setting above.
+- `reasoning:` on the agent block, beside `model:`, sets how hard the agent reasons: `none`, `low`, `medium`, `high`, `xhigh`, `max`, or `{ budget_tokens: 4096 }`. It reads the same on every provider; unset keeps the provider's default. The compiler sends each provider the field it reads: Gemini 3 and later get a thinking level (`none` is `MINIMAL`, then `LOW`, `MEDIUM`, `HIGH`); Gemini 2.x, and Claude 4.6 or older, get a thinking budget of 0, 2048, 8192 or 16384 tokens; every later Claude model gets adaptive thinking at an effort of `low`, `medium` or `high`, and `none` is that model's own off switch, sent at `low` effort; every other provider, and the gateway, gets an effort word, and where the provider lacks that word, its nearest setting above.
+- `xhigh` and `max` ask for more thought than `high`. They reach the models that take them: both on every later Claude model, `max` on Kimi K3 (where `xhigh` rounds up to it), and `xhigh` on GPT-5.2 and later and on grok-4.7. Every other model gets its highest setting instead, and the request's span carries `llm.reasoning.weakened`; the gateway gets `high` for any id. `npm run doctor -- --matrix` lists each path. Both cost more: `max` is Kimi K3's costliest effort.
 - A `budget_tokens` value goes as written to Gemini and to Claude 4.6 or older, and as the smallest level that covers it everywhere else, later Claude models included. The effort word is always sent too, because the gateway can serve any cloud id; a direct provider ignores the field it does not read. Changing the `model:` line keeps the setting. Unset, a later Claude model keeps its own default: it thinks, except Opus 4.7 and 4.8, which think only when asked.
 - Four provider limits: on Claude 4.6 or older, the adapter raises a budget under 1024 to 1024, the least Anthropic takes; on every Claude model, the Anthropic SDK refuses a non-streaming request whose output ceiling passes about 21000 tokens, and the adapter sets that ceiling to at least the thinking budget plus 2048, so a `budget_tokens` above about 19000 fails a non-streaming turn, while the levels stay under it; on Claude Opus 5 and 5.5, Fable and Mythos, `none` is adaptive thinking at `low` effort, so a little thinking remains, because Opus 5.5, Fable and Mythos cannot turn thinking off and Opus 5's off switch can write a tool call as text that never runs; Gemini 2.5 Pro rejects a budget of 0, so `none` fails on it.
 - `sampling:` on any agent: `temperature` (where the provider still exposes it; never sent to Claude), `top_p`, `stop`, `max_output_tokens`; each adapter sends the fields its provider takes. Thinking tokens count against `max_output_tokens`, so a reasoning agent with long output needs room; the Claude adapter raises its own ceiling to the thinking budget plus 2048 tokens, on every Claude model. A level counts as its budget (2048, 8192 or 16384), so `high`, or a later Claude model that thinks by default, gets at least 18432.
+- `tool_choice:` says which tools the model may call: `auto` (the default), `none`, `required` (some tool), or `{ name: lookup }` (that one tool). It reads the same on every provider; where a provider rejects forcing a tool, the adapter sends a weaker choice and the span carries `llm.tool_choice.weakened`.
 - `model_overrides:` gives one provider its own prompt nuance, keyed `gemini`, `anthropic`, `openai`, `xai`, `moonshot` or `ollama`; each entry holds `instruction` (replaces the agent's instruction on that provider) or `instruction_append` (added after it). The entry for the provider of the agent's `model:` applies, and a `fallback_model` gets the same instruction.
-- `generateContentConfig:` is the deprecated, Gemini-shaped spelling of `sampling:`, `output.mime` and `reasoning:` (as `thinkingConfig` and `reasoningEffort`). It still loads and behaves the same, with one deprecation line per file, but a `thinkingLevel` written for Gemini does nothing on Claude. An agent that sets a v2 key beside its v1 spelling fails to load. `npx melchizedek-codemod <file|dir>` rewrites a file to the v2 keys. Only `toolConfig` and the effort words `xhigh` and `max` still need `generateContentConfig:`. `topK`, `seed`, the penalties, `candidateCount`, `safetySettings` and `includeThoughts` reach no provider; the Gemini adapter asks for the thought trace itself whenever `reasoning:` is not `none`.
+- `generateContentConfig:` is the deprecated, Gemini-shaped spelling of `sampling:`, `tool_choice:`, `output.mime` and `reasoning:` (as `thinkingConfig` and `reasoningEffort`). It still loads and behaves the same, with one deprecation line per file, but a `thinkingLevel` written for Gemini does nothing on Claude. An agent that sets a v2 key beside its v1 spelling fails to load. `npx melchizedek-codemod <file|dir>` rewrites a file to the v2 keys. Only `toolConfig.functionCallingConfig.mode: VALIDATED` and Gemini's dynamic budget (`thinkingBudget: -1`) still need `generateContentConfig:`; the codemod drops `includeThoughts`. `topK`, `seed`, the penalties, `candidateCount`, `safetySettings` and `includeThoughts` reach no provider; the Gemini adapter asks for the thought trace itself whenever `reasoning:` is not `none`.
 - The framework's own pattern: data-gathering subagents on a lite model with `reasoning: none` and a tight output cap; synthesis on the stronger model with `reasoning: low` or higher and room to reason. The templates in `config/agents/templates/` follow it.
 Mixing providers in one syndicate:
 - Any agent in a graph can run on a different provider; `model_zoo.yaml` declares one lightweight agent per provider, and in a clone `npm run demo:models` sends one prompt through each.

package/skills/briefs/skills-readme.md

@@ -6,7 +6,7 @@ STRUCTURE (exact): an H1 `# Melchizedek agent skills`, then `##` sections in thi
 
 FACTS:
 What this is:
-- A suite of six Agent Skills (the open SKILL.md standard: one directory per skill, a SKILL.md with `name` and `description` frontmatter, optional supporting files) that teach a coding agent how to find, run, author, serve, remember with, and write with Melchizedek syndicates. They ship in the npm package melchizedek-agents and in the public repository, in `skills/`.
+- A suite of eleven Agent Skills (the open SKILL.md standard: one directory per skill, a SKILL.md with `name` and `description` frontmatter, optional supporting files) that teach a coding agent how to onboard a person from the credentials they have, and how to find, run, author, serve, remember with, and write with Melchizedek syndicates. They ship in the npm package melchizedek-agents and in the public repository, in `skills/`.
 The skills (name → what it teaches):
 - `melchizedek` → the entry point: where the syndicates are, what each starter-pack file does and costs, the doctor, running one interactively or one shot, and delegating a task from a coding agent.
 - `melchizedek-author` → designing or editing a syndicate YAML: layout, keys, instruction anatomy, tools by name, the two constraints that break a file, offline validation.
@@ -14,6 +14,8 @@ The skills (name → what it teaches):
 - `melchizedek-memory` → Supabase sessions and long-term memory: modes, schema, tools, extraction rules, inspection, erasure.
 - `melchizedek-models` → model ids and providers, keys, keyless Ollama, the gateway fallback, per-agent settings, the errors.
 - `melchizedek-scribe` → writing documents from a brief with the Scribe syndicate.
+- Five onboarding skills, written by hand rather than by the Scribe (they print their facts from `npx melchizedek-setup --level <id>`): `melchizedek-onboard` (triage to one of ten authentication levels), `melchizedek-onboard-local`, `melchizedek-onboard-keys`, `melchizedek-onboard-cloud`, `melchizedek-onboard-serve`.
+- `--agents-md` also writes a pointer block into the project's `AGENTS.md`.
 Install (three ways):
 - From the package, into this project's `.claude/skills/` and `.agents/skills/` (the two locations that between them reach Claude Code, Codex, Cursor, OpenCode and Gemini CLI): `npx melchizedek-skills install` after `npm install melchizedek-agents`. `--for <targets>` picks platforms from `claude, agents, codex, cursor, opencode, gemini, all`; `--global` writes the home-directory locations instead; `--dir <path>` writes one explicit directory; `--only <names>` installs a subset; `--force` overwrites a file that differs; `--dry-run` prints without writing. `npx melchizedek-skills paths` prints the locations; `npx melchizedek-skills list` prints the skills. In a clone: `npm run skills:install -- <same flags>`.
 - With the skills CLI from the public repository: `npx skills add jhwadman/melch-ai` lists the skills and installs the ones you choose into the agents you choose.

package/skills/melchizedek-models/SKILL.md

@@ -107,7 +107,7 @@ The runtime telemetry attributes every call to the upstream provider and records
 
 ## Settings per agent
 
-Set how hard an agent reasons with `reasoning:` on the agent block, beside `model:`. It takes `none`, `low`, `medium`, `high`, or `{ budget_tokens: 4096 }`, and reads the same on every provider. Leave it unset to keep the provider's default. The compiler sends each provider the field that provider reads:
+Set how hard an agent reasons with `reasoning:` on the agent block, beside `model:`. It takes `none`, `low`, `medium`, `high`, `xhigh`, `max`, or `{ budget_tokens: 4096 }`, and reads the same on every provider. Leave it unset to keep the provider's default. The compiler sends each provider the field that provider reads:
 
 | Provider | What `reasoning:` becomes |
 | --- | --- |
@@ -116,6 +116,8 @@ Set how hard an agent reasons with `reasoning:` on the agent block, beside `mode
 | Every later Claude model | adaptive thinking at an effort of `low`, `medium` or `high`; `none` is the model's own off switch, sent at `low` effort |
 | Every other provider, and the gateway | an effort word; where the provider lacks that word, its nearest setting above |
 
+`xhigh` and `max` ask for more thought than `high`. They reach the models that take them: both on every later Claude model, `max` on Kimi K3 (where `xhigh` rounds up to it), and `xhigh` on GPT-5.2 and later and on grok-4.7. Every other model gets its highest setting instead, and the request's span carries `llm.reasoning.weakened`; the gateway gets `high` for any id. `npm run doctor -- --matrix` lists each path. Both cost more: `max` is Kimi K3's costliest effort.
+
 A `budget_tokens` value goes as written to Gemini and to Claude 4.6 or older, and as the smallest level that covers it everywhere else, later Claude models included. Because the gateway can serve any cloud id, the effort word is always sent as well, and a direct provider ignores the field it does not read. Change the `model:` line and the setting carries over. Unset, a later Claude model keeps its own default: it thinks, except Opus 4.7 and 4.8, which think only when asked.
 
 Four limits apply. On Claude 4.6 or older, the adapter raises a budget under 1024 to 1024, the least Anthropic takes. On every Claude model, the Anthropic SDK refuses a non-streaming request whose output ceiling passes about 21000 tokens. The adapter sets that ceiling to at least the thinking budget plus 2048, so a `budget_tokens` above about 19000 fails a non-streaming turn. The levels stay under it. On Claude Opus 5 and 5.5, Fable and Mythos, `none` is adaptive thinking at `low` effort, so a little thinking remains: Opus 5.5, Fable and Mythos cannot turn thinking off, and Opus 5's off switch can write a tool call as text that never runs. Gemini 2.5 Pro rejects a budget of 0, so `none` fails on it.
@@ -125,9 +127,11 @@ You can configure sampling under `sampling:` on any agent in the syndicate YAML,
 - `top_p` and `stop`: nucleus sampling and stop sequences.
 - `max_output_tokens`: caps total token generation. Thinking tokens count against it, so a reasoning agent with long output needs room. The Claude adapter raises its own ceiling to the thinking budget plus 2048 tokens, on every Claude model. A level counts as its budget (2048, 8192 or 16384), so `high`, or a later Claude model that thinks by default, gets at least 18432.
 
+`tool_choice:` says which tools the model may call: `auto` (the default), `none`, `required` (some tool), or `{ name: lookup }` (that one tool). It reads the same on every provider. Where a provider rejects forcing a tool, the adapter sends a weaker choice and the span carries `llm.tool_choice.weakened`.
+
 `model_overrides:` gives one provider its own prompt nuance. Key it by `gemini`, `anthropic`, `openai`, `xai`, `moonshot`, or `ollama`; each entry holds `instruction`, which replaces the agent instruction on that provider, or `instruction_append`, which adds text after it. The entry for the provider of the agent `model:` applies, and a `fallback_model` gets the same instruction.
 
-`generateContentConfig:` is the deprecated, Gemini-shaped spelling of `sampling:`, `output.mime`, and `reasoning:` (as `thinkingConfig` and `reasoningEffort`). It still loads and behaves the same, with one deprecation line per file, but a `thinkingLevel` written for Gemini does nothing on Claude. An agent that sets a v2 key beside its v1 spelling fails to load. `npx melchizedek-codemod <file|dir>` rewrites a file to the v2 keys. Only `toolConfig` and the effort words `xhigh` and `max` still need `generateContentConfig:`. `topK`, `seed`, the penalties, `candidateCount`, `safetySettings`, and `includeThoughts` reach no provider; the Gemini adapter asks for the thought trace itself whenever `reasoning:` is not `none`.
+`generateContentConfig:` is the deprecated, Gemini-shaped spelling of `sampling:`, `tool_choice:`, `output.mime`, and `reasoning:` (as `thinkingConfig` and `reasoningEffort`). It still loads and behaves the same, with one deprecation line per file, but a `thinkingLevel` written for Gemini does nothing on Claude. An agent that sets a v2 key beside its v1 spelling fails to load. `npx melchizedek-codemod <file|dir>` rewrites a file to the v2 keys. Only `toolConfig.functionCallingConfig.mode: VALIDATED` and Gemini's dynamic budget (`thinkingBudget: -1`) still need `generateContentConfig:`; the codemod drops `includeThoughts`. `topK`, `seed`, the penalties, `candidateCount`, `safetySettings`, and `includeThoughts` reach no provider; the Gemini adapter asks for the thought trace itself whenever `reasoning:` is not `none`.
 
 The framework's own pattern places data-gathering subagents on a lite model with `reasoning: none` and a tight output cap, while synthesis runs on a stronger model with `reasoning: low` or higher and room to reason. The templates in `config/agents/templates/` follow it.
 

package/skills/melchizedek-onboard/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: melchizedek-onboard
+description: "Onboard a person to Melchizedek from whatever credentials they have: ask what they have (nothing, one or several provider API keys, a gateway key, Vertex AI / Bedrock / Azure access, a server to put in front of other people, OAuth tools, a ChatGPT plan to use on their own machine, or a Codex, Claude.ai or Gemini CLI sign-in), route them to one authentication level, and walk its startup guide without ever handling a key. Use when someone is setting up melchizedek-agents for the first time, asks which keys they need, says 'I have an X key', 'I have ChatGPT Plus' or 'I have a Codex login', or asks how to get started."
+---
+
+## What this skill does
+
+It turns "what do you have?" into one of ten authentication levels and the startup guide for it. The guides are generated by the engine itself, so you print them instead of restating them:
+
+```bash
+npx melchizedek-setup --list                 # the ten levels
+npx melchizedek-setup --level <id|number>    # one level's guide
+npx melchizedek-setup --auto                 # detect from the environment, names only
+```
+
+In a clone of the repository, use `npm run setup -- <flags>` instead of `npx melchizedek-setup`. The same guides are in `ONBOARDING.md`.
+
+## The rules that never bend
+
+- Never ask the person to paste a key, token or secret into the chat, and never read one from their files or shell history. A pasted key lives in the transcript forever.
+- Never print a value from `.env`. To check what is set, run `npx melchizedek-setup --auto` or `npx melchizedek-doctor`; both report names and set or unset only.
+- The person types every value into `.env` in their own editor. You may create `.env` with names left blank: `npx melchizedek-setup --level <id> --write-env`. It never overwrites an existing `.env` and refuses unless git ignores `.env`.
+- Never reuse another app's sign-in (the Codex CLI's login, Claude.ai, Gemini CLI) as a model credential, and never read its token files. Route that person to level 10, which names the sanctioned alternative.
+- A ChatGPT plan is used only through the engine's own Sign in with ChatGPT (level 9): the person runs `npx melchizedek-setup --chatgpt-signin` and approves in their own browser. It is for their own machine only; never set it up for a server.
+
+## Triage
+
+1. Run `npx melchizedek-setup --auto`. If it already detects a level beyond 1, confirm with the person that this is what they want and continue from that guide.
+2. Otherwise ask one question: "What do you have: nothing yet, an API key from a model provider, a gateway key, cloud platform access, a ChatGPT plan, or a Claude or Gemini sign-in? And will other people or backends call your agents?"
+3. Route by the answer:
+
+| They have | Level | Follow |
+|---|---|---|
+| Nothing, or want everything on their machine | 1 `local` | `melchizedek-onboard-local` |
+| One key from Google AI Studio, Anthropic, OpenAI, xAI or Moonshot | 2 `one-provider` | `melchizedek-onboard-keys` |
+| Keys from several of those | 3 `several-providers` | `melchizedek-onboard-keys` |
+| A Vercel AI Gateway or OpenRouter key | 4 `gateway` | `melchizedek-onboard-keys` |
+| Google Cloud (Vertex AI), AWS (Bedrock) or Azure OpenAI access | 5 `cloud-platform` | `melchizedek-onboard-cloud` |
+| Callers who fund their own model calls | 6 `byok` | `melchizedek-onboard-serve` |
+| Other backends or users calling the server | 7 `caller-tokens` | `melchizedek-onboard-serve` |
+| Tools that act for each user on a third-party API | 8 `oauth-grants` | `melchizedek-onboard-serve` |
+| A ChatGPT plan, to use on their own machine | 9 `chatgpt-signin` | `melchizedek-onboard-keys` |
+| A Codex CLI login, a Claude.ai or a Gemini CLI sign-in only | 10 `subscription-signin` | `melchizedek-onboard-keys` |
+
+Levels 6 to 8 sit on top of a model level (1 to 5): settle how models are paid for first.
+
+4. Print the level's guide with `--level <id>` and walk it step by step: the person sets the variables, you run the doctor command the guide names and read its verdicts back to them, then you run the first command.
+
+## Use melch from Claude Code or Codex
+
+Once a level is confirmed, the person can call their syndicates from inside their coding agent: `melchizedek-mcp` makes each syndicate an MCP tool (`{ message, session_id? }`), plus `melch_resume` for a turn that pauses. Register it from the project directory, where `.env` and `config/agents/` live:
+
+```bash
+claude mcp add melch -- npx melchizedek-mcp --syndicate <id>
+```
+
+For Codex, add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.melch]
+command = "npx"
+args = ["-y", "-p", "melchizedek-agents", "melchizedek-mcp", "--syndicate", "<id>"]
+cwd = "/path/to/the/project"
+tool_timeout_sec = 900
+```
+
+When a result says an approval is waiting, ask the person and pass their decision to `melch_resume` with `approve`; never approve on their behalf. Keys stay in `.env`: the MCP registration names no key.
+
+## Done when
+
+The doctor shows the level's confirmation (the guide's **Confirm** line), and the first command has answered once. Then hand over to the `melchizedek` skill for the catalog of syndicates.

package/skills/melchizedek-onboard-cloud/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: melchizedek-onboard-cloud
+description: "Onboard a person to Melchizedek through their cloud account instead of vendor API keys: Gemini or Claude on Google Vertex AI (Application Default Credentials), Claude on Amazon Bedrock (the AWS credential chain), or GPT on Azure OpenAI (an Azure key or Entra ID). Use when someone has a Google Cloud project, AWS access, or an Azure OpenAI resource, needs data to stay in their cloud, or sees an endpoint problem from the doctor."
+---
+
+## The level
+
+Level 5, `cloud-platform`. The model id still picks the provider; `GEMINI_PLATFORM`, `ANTHROPIC_PLATFORM` and `OPENAI_PLATFORM` pick the cloud it is reached through. Print the guide first:
+
+```bash
+npx melchizedek-setup --level cloud-platform     # in a clone: npm run setup -- --level cloud-platform
+```
+
+## Steps per cloud
+
+The person signs in to their cloud with that cloud's own tools; you never handle the credential.
+
+- **Gemini on Vertex AI.** They run `gcloud auth application-default login` (or the deployment uses a service account). In `.env`: `GEMINI_PLATFORM=vertex`, `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION`.
+- **Claude on Vertex AI.** `npm install @anthropic-ai/vertex-sdk`. In `.env`: `ANTHROPIC_PLATFORM=vertex`, `ANTHROPIC_VERTEX_PROJECT_ID` (or `GOOGLE_CLOUD_PROJECT`), `CLOUD_ML_REGION` (or `GOOGLE_CLOUD_LOCATION`). Credentials are Google ADC, as above.
+- **Claude on Amazon Bedrock.** `npm install @anthropic-ai/bedrock-sdk`. In `.env`: `ANTHROPIC_PLATFORM=bedrock`, `AWS_REGION`. Credentials come from the AWS chain (a profile, SSO, or the instance role). Bedrock model ids differ from Anthropic's: map them with `ANTHROPIC_MODEL_MAP` (a JSON object of YAML id to Bedrock id).
+- **GPT on Azure OpenAI.** In `.env`: `OPENAI_PLATFORM=azure`, `AZURE_OPENAI_ENDPOINT`, and either `AZURE_OPENAI_API_KEY` or Entra ID (`npm install @azure/identity`, then `az login` or a managed identity). Map YAML ids to deployment names with `OPENAI_MODEL_MAP`.
+
+Use `npx melchizedek-setup --level cloud-platform --write-env` to create `.env` with these names blank when there is none.
+
+## Confirm
+
+Run `npx melchizedek-doctor`. Each provider on a cloud prints one `endpoint` line; a ✗ names the missing variable or the uninstalled SDK. The doctor does not exercise the cloud's credential chain, so the first command is the real test:
+
+```bash
+npx melchizedek-init --template research_brief     # Gemini; for Claude use the claude example
+npx melchizedek-chat --syndicate research_brief
+```
+
+## Say this up front
+
+- These paths are tested against mocks and have not been run against the live clouds from the engine's repository; the doctor says so.
+- Anthropic's and OpenAI's server-side `web_search` are not sent on Bedrock, Claude on Vertex AI or Azure. Gemini grounding works on Vertex AI.
+- Model availability differs by region: a `Model not found` usually means the region or the model map, not the code.

package/skills/melchizedek-onboard-keys/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: melchizedek-onboard-keys
+description: "Onboard a person to Melchizedek with provider API keys: one key (Gemini, Anthropic, OpenAI, xAI or Moonshot), several, or one Vercel AI Gateway / OpenRouter key, or their ChatGPT plan on their own machine through Sign in with ChatGPT, and answer honestly when they only have a Codex, Claude.ai or Gemini CLI sign-in. Use when someone says 'I have an OpenAI key', 'I have keys for Claude and Gemini', 'I have an OpenRouter key', 'I have ChatGPT Plus', 'can I use my Codex login', or asks which key unlocks which syndicate."
+---
+
+## The levels
+
+| Level | Id | Guide |
+|---|---|---|
+| 2 | `one-provider` | one provider's key funds every agent on that provider |
+| 3 | `several-providers` | each key funds its own provider; a syndicate may mix them |
+| 4 | `gateway` | one gateway key serves every cloud id whose direct key is absent |
+| 9 | `chatgpt-signin` | Sign in with ChatGPT: OpenAI ids on the person's ChatGPT plan, on their own machine only |
+| 10 | `subscription-signin` | another app's sign-in is not a model credential; the sanctioned route instead |
+
+Print the guide for the level before you start: `npx melchizedek-setup --level <id>` (in a clone, `npm run setup -- --level <id>`).
+
+## Steps for a key (levels 2 to 4)
+
+1. Create `.env` with the names left blank, if there is none: `npx melchizedek-setup --level <id> --write-env`. It refuses unless git ignores `.env`; if it refuses, add `.env` to `.gitignore` first.
+2. Tell the person which variable to fill in and where the key comes from (the guide's table: Google AI Studio, the Anthropic console, the OpenAI platform, the xAI console, the Moonshot platform, Vercel or OpenRouter). They open `.env` in their editor and type the value. Never ask for it in chat.
+3. Run `npx melchizedek-doctor`. Read the providers line back: a ✓ beside each provider they set, `◇ via gateway` for providers served by the gateway. Each blocked file names the one variable that would unblock it.
+4. Run the guide's first commands. With a Gemini key, `research_brief` is a good first template; with only an Anthropic key, `claude` is the shipped example; for any other provider, change a template's `model:` lines to that provider's ids and run the doctor again.
+
+## What to tell them about the gateway
+
+It is a fallback, never a preempt: a direct key set beside it wins for its provider. On the gateway path, native search is dropped (Gemini grounding, Anthropic and OpenAI `web_search`, xAI `x_search`), and long-term memory's embedder still needs `GOOGLE_GENAI_API_KEY` (or `MEMORY_EMBEDDING_PROVIDER=openai` or `ollama`). A model id the gateway rejects is fixed with `MODEL_GATEWAY_MODEL_MAP`, not in code.
+
+## Sign in with ChatGPT (level 9, local only)
+
+OpenAI documents a plan-usage sign-in for open-source apps that run on the user's own machine, and the engine implements it as its own app registration.
+
+1. The person runs `npx melchizedek-setup --chatgpt-signin` (in a clone, `npm run setup -- --chatgpt-signin`) and approves in their own browser. You never see, copy or move the stored tokens; they live outside the repository, mode 600.
+2. `OPENAI_API_KEY` must be blank for the sign-in to carry OpenAI ids; a key wins.
+3. Run `npx melchizedek-doctor`: the providers line shows `ChatGPT sign-in, local only`, and the `chatgpt` line reads `signed in · carries OpenAI ids · local only`.
+4. Point a syndicate's `model:` lines at a GPT id their ChatGPT account offers, then chat.
+
+Tell them: it is a preview (the Responses API only, streamed, no temperature or output-token cap), their plan's usage limits apply, and it is for their machine only. `melchizedek-serve` and `melchizedek-worker` refuse to start on it; a server needs `OPENAI_API_KEY` or Azure OpenAI. Sign out with `--chatgpt-signout`.
+
+## A subscription sign-in (level 10)
+
+Say plainly what is and is not possible, then route:
+
+- A Codex CLI login, a Claude.ai or a Gemini CLI sign-in pays for that vendor's own apps. The engine does not read, reuse or relay those tokens, and you must not wire one in or read their files.
+- Anthropic and Google state that third-party software may not use those sign-ins. For OpenAI, the sanctioned way to use a ChatGPT plan is level 9, the engine's own Sign in with ChatGPT; copying the Codex CLI's token is not that flow.
+- The sanctioned routes: an API key from the same vendor (level 2), or its cloud platform (Bedrock or Vertex AI for Claude, Vertex AI for Gemini, Azure OpenAI for GPT; level 5, `melchizedek-onboard-cloud`). Google AI Studio has a free tier, and local models need nothing (level 1).
+- The sign-in still has a use here: it pays for the coding agent (you) that drives this repository.

package/skills/melchizedek-onboard-local/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: melchizedek-onboard-local
+description: "Onboard a person to Melchizedek with no API key at all: install Ollama, pull an open-weight model, and run the keyless syndicates entirely on their machine. Use when someone has no provider key, wants nothing to leave their machine, asks for the free or offline path, or meets OLLAMA_UNREACHABLE."
+---
+
+## The level
+
+Level 1, `local`. Every agent whose model id starts with `ollama/` runs through Ollama's OpenAI-compatible endpoint on the person's machine. No account, no key. Print the current guide first:
+
+```bash
+npx melchizedek-setup --level local      # in a clone: npm run setup -- --level local
+```
+
+## Steps
+
+1. Check Node.js: `node --version` must be 22.6 or newer.
+2. The person installs Ollama from https://ollama.com (an installer is theirs to run). Then:
+
+   ```bash
+   ollama pull qwen3:8b
+   ```
+
+3. In a project that installed the package, copy the keyless template; in a clone, the keyless examples are already there:
+
+   ```bash
+   npx melchizedek-init --template conversational
+   npx melchizedek-chat --syndicate conversational
+   # clone: npm run syndicate:assistant (or syndicate:tutor, syndicate:council)
+   ```
+
+4. Confirm with the doctor (`npx melchizedek-doctor`, or `npm run doctor` in a clone): the providers line shows `Ollama (local) local`, and the keyless files read `ready — local, no key`.
+
+## When it fails
+
+- `OLLAMA_UNREACHABLE`: Ollama is not running. Start the app or `ollama serve`, then `ollama list` to see the model is pulled.
+- An answer that stops mid-page on a summarizing task: Ollama's default context is 4,096 tokens. Restart it with `OLLAMA_CONTEXT_LENGTH=16384 ollama serve`.
+- A different Ollama host: set `OLLAMA_BASE_URL` (shape `http://host:11434/v1`) in `.env`. No key is involved.
+
+## Next
+
+Server-side search tools are not available locally. When the person gets a provider key, switch to `melchizedek-onboard-keys`; the keyless files keep working beside it.

package/skills/melchizedek-onboard-serve/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: melchizedek-onboard-serve
+description: "Onboard an operator who will serve Melchizedek agents to other people or backends over A2A: who pays for model calls (the server's keys or each caller's own, BYOK), who a caller is (A2A_AUTH: caller tokens, JWT, a gateway header, or one shared secret), the public-URL posture, and OAuth tool grants that act for each end user. Use when someone asks to deploy or expose the server, to let customers bring their own key, to issue tokens to calling backends, or to connect a tool to a user's third-party account."
+---
+
+## The levels
+
+| Level | Id | Settles |
+|---|---|---|
+| 6 | `byok` | callers fund their own model calls with `X-API-Key` and `X-Provider` |
+| 7 | `caller-tokens` | who a caller is: `A2A_AUTH=callers`, `jwt`, `header` or `secret` |
+| 8 | `oauth-grants` | tools that send a third-party token for each end user |
+
+They sit on top of a model level (1 to 5): settle how the server's own models are paid for first. Print a guide with `npx melchizedek-setup --level <id>` (in a clone, `npm run setup -- --level <id>`).
+
+## Identity first (level 7)
+
+1. Pick the mode with the operator. Prefer `callers` (one token per calling backend) or `jwt` (their identity provider) on anything public. `header` is for an authenticating gateway in front. `secret` is one shared secret: any holder can act as any user.
+2. For `callers`, mint a token per backend so it never lands in a transcript:
+
+   ```bash
+   npx melchizedek-serve --new-caller my-backend --token-file "$HOME/my-backend.token"
+   ```
+
+   It writes the token to a new mode-600 file and prints only the `A2A_CALLERS` entry, which holds the token's SHA-256. The operator adds that entry to `.env`, moves the token into the calling backend's secret store, and deletes the file. Do not run `--new-caller` without `--token-file` in an agent session.
+3. On a public deployment, `PUBLIC_URL` makes the server refuse to start until `A2A_AUTH`, `A2A_SERVED_AGENTS` and `A2A_TRUST_PROXY` are set explicitly. That is intended; set them, do not work around it.
+4. Run `npx melchizedek-doctor`: the `serving` line names the mode and, with a ✗, any variable the server would stop on.
+
+## Who pays (level 6)
+
+`A2A_KEY_MODE=byok` makes each caller's `X-API-Key` fund agents on the provider named by `X-Provider`. Agents on other providers, tools and memory extraction still use the server's keys. Under `A2A_AUTH=secret` only, byok also scopes data by a hash of the caller's key; with caller tokens or JWTs, the identity scopes data and byok only pays.
+
+## OAuth tool grants (level 8)
+
+1. The operator generates the sealing key themselves (`openssl rand -base64 32`) and types it into `MELCHIZEDEK_CREDENTIAL_KEY`. It must stay out of the database and its backups.
+2. `OAUTH_REDIRECT_URI` is the https callback registered at every provider, with no query string.
+3. `MELCHIZEDEK_OAUTH_HOSTS` binds each provider to the hosts its tokens may reach (`provider=host,host;provider=host`). Unset, authorization-code grants are refused.
+4. The default callback identity (`OAUTH_CALLBACK_IDENTITY=required`) needs `A2A_AUTH=header` behind a gateway; `state` relaxes it, and a forwarded consent link can then connect the wrong account. Say so before choosing it.
+5. Each grant's client id and secret come from variables the YAML names; the doctor lists them by name for every `⚿` line. `systems_operator` carries a commented `mcp_auth` block to start from.
+
+## Done when
+
+The doctor's `serving` (and, for level 8, `oauth`) lines show no ✗, the server starts, and one authenticated call answers: `node demo/a2a_demo.mjs` is a two-turn client for the secret mode.