melchizedek-agents 1.1.0 → 1.2.0

package/ONBOARDING.md

@@ -0,0 +1,339 @@
+<!-- Generated by lib/onboarding.ts: `npm run setup -- --markdown > ONBOARDING.md`. Do not edit by hand; tests/onboarding.test.ts holds this file equal to the generator. -->
+
+# Onboarding: start from what you have
+
+Start with `npx melchizedek-setup` (in a clone, `npm run setup`). It opens a menu of the levels below and prints the guide for the one you pick; `--auto` reads your environment, names only, and prints the guide for the highest level it detects. Every guide lists variable names and shapes, never values: you type the values into `.env` yourself.
+
+In a clone, the commands are spelled as npm scripts (`npm run doctor`, `npm run chat:syndicate -- --syndicate <name>`); the menu prints that spelling there.
+
+| # | 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 or Moonshot) | `--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` |
+| 6 | Serving over A2A where each caller brings its own model key (BYOK) | `--level byok` |
+| 7 | Serving to other backends or users with their own tokens (A2A_AUTH) | `--level caller-tokens` |
+| 8 | Tools that act for end users on third-party APIs (OAuth grants) | `--level oauth-grants` |
+| 9 | A ChatGPT / Codex, Claude.ai or Gemini CLI sign-in (no API key) | `--level subscription-signin` |
+
+## 1. No keys: local models only
+
+Every agent whose model id starts with `ollama/` runs on your machine through Ollama. No account, no key, and no data leaves the machine. Install Ollama from https://ollama.com and pull a model: `ollama pull qwen3:8b`.
+
+**Set in `.env`** (names and shapes only; you type the values yourself):
+
+| Variable | Shape | What it does |
+|---|---|---|
+| `OLLAMA_BASE_URL` | http://localhost:11434/v1 | optional: only for a non-default Ollama endpoint |
+
+**Confirm:** `npx melchizedek-doctor`: the providers line shows `Ollama (local) local`, and the keyless files read `ready — local, no key`.
+
+**Runs at this level:**
+
+- keyless: conversational (template), assistant (example), council (example), tutor (example)
+
+**First commands:**
+
+```bash
+npx melchizedek-init --template conversational
+npx melchizedek-chat --syndicate conversational
+```
+
+**Notes:**
+
+- Server-side search tools (web_search, google_search, x_search) are not available on Ollama; the doctor lists what each agent drops.
+- Ollama serves a 4,096-token context by default; start it with `OLLAMA_CONTEXT_LENGTH=16384 ollama serve` before summarizing web pages.
+
+**Onboarding skill:** `melchizedek-onboard-local` (`npx melchizedek-setup --level local` prints this guide)
+
+## 2. One provider's API key
+
+The model id's prefix picks the provider, and that provider's key funds it. One key runs every file whose agents all use that provider. A Gemini key runs the most shipped files and also powers long-term memory's embeddings.
+
+**Set in `.env`** (names and shapes only; you type the values yourself):
+
+| Variable | Shape | What it does |
+|---|---|---|
+| `GOOGLE_GENAI_API_KEY` | an API key from https://aistudio.google.com | Google Gemini: model ids gemini-* (and any id without another prefix); also the default embedder for long-term memory (GEMINI_API_KEY is accepted too) |
+| `ANTHROPIC_API_KEY` | an API key from https://console.anthropic.com | Anthropic Claude: model ids claude-* |
+| `OPENAI_API_KEY` | an API key from https://platform.openai.com/api-keys | OpenAI GPT: model ids gpt-*, o<digit>* |
+| `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-* |
+
+**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), augustin (example), cartographers (example), critic (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)
+- with no key at all: conversational (template), assistant (example), council (example), tutor (example)
+
+**First commands:**
+
+```bash
+npx melchizedek-init --template research_brief
+npx melchizedek-chat --syndicate research_brief
+```
+
+**Notes:**
+
+- Set only the one variable you have; leave the others blank. The doctor names, per file, the variable that would unblock it.
+- To run a shipped file on your provider, change its `model:` lines (for example `gemini-3.8-flash` to `claude-sonnet-4-6`); `doctor` then shows it ready.
+
+**Onboarding skill:** `melchizedek-onboard-keys` (`npx melchizedek-setup --level one-provider` prints this guide)
+
+## 3. Several providers
+
+Each key funds its own provider, and a syndicate may mix them: one agent on Claude, another on Gemini, a third local. A direct key always serves its provider at full fidelity (native search included).
+
+**Set in `.env`** (names and shapes only; you type the values yourself):
+
+| Variable | Shape | What it does |
+|---|---|---|
+| `GOOGLE_GENAI_API_KEY` | an API key from https://aistudio.google.com | Google Gemini: model ids gemini-* (and any id without another prefix); also the default embedder for long-term memory (GEMINI_API_KEY is accepted too) |
+| `ANTHROPIC_API_KEY` | an API key from https://console.anthropic.com | Anthropic Claude: model ids claude-* |
+| `OPENAI_API_KEY` | an API key from https://platform.openai.com/api-keys | OpenAI GPT: model ids gpt-*, o<digit>* |
+| `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-* |
+
+**Confirm:** `npx melchizedek-doctor`: a ✓ beside each provider you set; `multi-provider` files read `ready` once every provider they use has its key.
+
+**Runs at this level:**
+
+- multi-provider: model_zoo (example)
+- plus every single-provider file whose key you set (see level 2)
+
+**First commands:**
+
+```bash
+npx melchizedek-init --template model_zoo
+npx melchizedek-chat --syndicate model_zoo
+```
+
+**Notes:**
+
+- A provider you have no key for can still be served by a gateway (level 4); a direct key set beside it wins for its own provider.
+
+**Onboarding skill:** `melchizedek-onboard-keys` (`npx melchizedek-setup --level several-providers` prints this guide)
+
+## 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.
+
+**Set in `.env`** (names and shapes only; you type the values yourself):
+
+| Variable | Shape | What it does |
+|---|---|---|
+| `MODEL_GATEWAY` | vercel | openrouter | which gateway |
+| `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 |
+
+**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), augustin (example), cartographers (example), critic (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)
+
+**First commands:**
+
+```bash
+npx melchizedek-init --template research_brief
+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.
+
+**Onboarding skill:** `melchizedek-onboard-keys` (`npx melchizedek-setup --level gateway` prints this guide)
+
+## 5. Cloud platform credentials
+
+The model id still picks the provider; these variables pick the cloud it is reached through, authenticated by that cloud's own credential chain instead of a vendor API key. Gemini and Claude on Vertex AI use Google Application Default Credentials (`gcloud auth application-default login`, or a service account); Claude on Bedrock uses the AWS credential chain; GPT on Azure uses an Azure key or Entra ID.
+
+**Set in `.env`** (names and shapes only; you type the values yourself):
+
+| Variable | Shape | What it does |
+|---|---|---|
+| `GEMINI_PLATFORM` | vertex | Gemini on Vertex AI (ADC) |
+| `GOOGLE_CLOUD_PROJECT` | a Google Cloud project id | Vertex AI project |
+| `GOOGLE_CLOUD_LOCATION` | a region, or global | Vertex AI location |
+| `ANTHROPIC_PLATFORM` | bedrock | vertex | Claude on Bedrock (`npm install @anthropic-ai/bedrock-sdk`) or Vertex AI (`npm install @anthropic-ai/vertex-sdk`) |
+| `AWS_REGION` | an AWS region, e.g. us-east-1 | Bedrock region; credentials come from the AWS chain (profile, role, SSO) |
+| `ANTHROPIC_VERTEX_PROJECT_ID` | a Google Cloud project id | Claude on Vertex AI (falls back to GOOGLE_CLOUD_PROJECT) |
+| `CLOUD_ML_REGION` | a region | Claude on Vertex AI (falls back to GOOGLE_CLOUD_LOCATION) |
+| `OPENAI_PLATFORM` | azure | GPT on Azure OpenAI |
+| `AZURE_OPENAI_ENDPOINT` | https://<resource>.openai.azure.com | the Azure OpenAI resource |
+| `AZURE_OPENAI_API_KEY` | an Azure OpenAI key | optional: without it, Entra ID (`npm install @azure/identity`) |
+| `ANTHROPIC_MODEL_MAP` | JSON: {"yaml-id":"platform-id"} | optional: Bedrock or Vertex model ids (OPENAI_MODEL_MAP for Azure deployments, GEMINI_MODEL_MAP likewise) |
+
+**Confirm:** `npx melchizedek-doctor`: one `endpoint` line per provider on a cloud platform, with no ✗; the credential chain itself is not exercised by the doctor.
+
+**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), augustin (example), cartographers (example), critic (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)
+
+**First commands:**
+
+```bash
+npx melchizedek-init --template research_brief
+npx melchizedek-chat --syndicate research_brief
+```
+
+**Notes:**
+
+- The Vertex AI, Bedrock and Azure paths are tested against mocks and have not been run against the live clouds from this 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.
+
+**Onboarding skill:** `melchizedek-onboard-cloud` (`npx melchizedek-setup --level cloud-platform` prints this guide)
+
+## 6. Per-caller keys when serving over A2A (BYOK)
+
+The A2A server lets each caller fund its own inference: the caller sends its key in `X-API-Key` and the provider in `X-Provider`, and agents on that provider run on that key for that request. Agents on other providers, tools and memory extraction still run on the server's keys.
+
+**Set in `.env`** (names and shapes only; you type the values yourself):
+
+| Variable | Shape | What it does |
+|---|---|---|
+| `A2A_KEY_MODE` | byok | callers' X-API-Key funds X-Provider (default: server) |
+| `A2A_SERVER_SECRET` | 64 hex characters (`openssl rand -hex 32`) | the bearer secret callers present (or caller tokens: level 7) |
+
+**Confirm:** `npx melchizedek-doctor`: a `serving` line reading `A2A_KEY_MODE=byok` with no ✗.
+
+**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
+
+**First commands:**
+
+```bash
+npx melchizedek-init --template conversational
+npx melchizedek-serve conversational.yaml
+```
+
+**Notes:**
+
+- Under A2A_AUTH=secret, 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.
+- Without A2A_SERVER_SECRET or caller tokens the server binds 127.0.0.1 only; set one before anyone else calls it.
+
+**Onboarding skill:** `melchizedek-onboard-serve` (`npx melchizedek-setup --level byok` prints this guide)
+
+## 7. Serving with caller tokens (A2A_AUTH)
+
+A2A_AUTH decides who a caller is, and so whose data a request touches. `callers` gives each calling backend its own bearer token (the config holds only its SHA-256); `jwt` accepts your identity provider's tokens; `header` trusts a user header set by an authenticating gateway that alone holds the secret; `secret` (the default) is one shared bearer secret.
+
+**Set in `.env`** (names and shapes only; you type the values yourself):
+
+| Variable | Shape | What it does |
+|---|---|---|
+| `A2A_AUTH` | callers | jwt | header | secret | the identity mode (required with PUBLIC_URL) |
+| `A2A_CALLERS` | name:sha256[:scope];name:sha256[:scope] | callers: mint each with `melchizedek-serve --new-caller <name>` |
+| `A2A_JWT_ISSUER` | https://your-idp.example/ | jwt: required iss |
+| `A2A_JWT_AUDIENCE` | an audience string | jwt: required aud |
+| `A2A_JWT_JWKS_URL` | https URL of the JWKS | jwt: RS256/ES256 keys (or A2A_JWT_SECRET, HS256, 32+ characters) |
+| `A2A_TRUSTED_USER_HEADER` | a header name, e.g. X-Authenticated-User | header: set by your gateway |
+| `A2A_SERVER_SECRET` | 64 hex characters (`openssl rand -hex 32`) | secret and header modes |
+| `PUBLIC_URL` | https://agents.example.com | only on a public deployment; it then requires the three below |
+| `A2A_SERVED_AGENTS` | comma list of agent ids, or * | which agents the server answers (required with PUBLIC_URL) |
+| `A2A_TRUST_PROXY` | 1 behind one load balancer, or false | required with PUBLIC_URL |
+
+**Confirm:** `npx melchizedek-doctor`: a `serving` line naming your A2A_AUTH mode with no ✗.
+
+**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
+
+**First commands:**
+
+```bash
+npx melchizedek-init --template support_triage
+npx melchizedek-serve --new-caller my-backend --token-file "$HOME/my-backend.token"
+npx melchizedek-serve support_triage.yaml
+```
+
+**Notes:**
+
+- `--new-caller --token-file` writes the token to a new mode-600 file outside the project and prints only the `A2A_CALLERS` entry (a hash); move the token into the calling backend's secret store and delete the file. Without `--token-file` the token is printed once, so do not run it where a transcript is kept.
+- Prefer callers or jwt on a public URL: under `secret`, any holder of the secret can act as any user by naming them in X-User-Id.
+
+**Onboarding skill:** `melchizedek-onboard-serve` (`npx melchizedek-setup --level caller-tokens` prints this guide)
+
+## 8. OAuth tool grants for end users
+
+A tool declared with `auth: { oauth2 }` (or an MCP server with `mcp_auth`) sends a third-party token. An authorization_code grant pauses the turn until the user consents; the token is sealed per user with the credential key and only sent to hosts the operator binds. A client_credentials grant uses the server's own client.
+
+**Set in `.env`** (names and shapes only; you type the values yourself):
+
+| Variable | Shape | What it does |
+|---|---|---|
+| `MELCHIZEDEK_CREDENTIAL_KEY` | 32 random bytes, base64 or 64 hex (`openssl rand -base64 32`) | seals each user's tokens; keep it out of the database and its backups |
+| `OAUTH_REDIRECT_URI` | https://agents.example.com/oauth/callback (no query) | the consent callback, registered at every provider; needs the key |
+| `MELCHIZEDEK_OAUTH_HOSTS` | provider=host,host;provider=host | the hosts each provider's tokens may go to; unset, authorization_code grants are refused |
+| `OAUTH_CALLBACK_IDENTITY` | required | state | required (default) needs A2A_AUTH=header behind a gateway |
+| `DATABASE_URL` | postgres://… | durable sealed store; without it, grants live in process memory |
+
+**Confirm:** `npx melchizedek-doctor`: an `oauth` line with no ✗, and each `⚿` grant line naming no unset variable.
+
+**Runs at this level:**
+
+- declares a grant: no shipped file declares one active
+- carries a commented grant to uncomment: systems_operator (template)
+
+**First commands:**
+
+```bash
+npx melchizedek-init --template systems_operator
+# uncomment its mcp_auth block, then:
+npx melchizedek-doctor   # names the client id and secret variables the grant reads
+npx melchizedek-serve systems_operator.yaml
+```
+
+**Notes:**
+
+- Each grant's client id and secret are read from variables the YAML names (client_id_env, client_secret_env); the framework's own settings are refused there.
+- This level sits on top of a serving level: set A2A_AUTH first (level 7).
+
+**Onboarding skill:** `melchizedek-onboard-serve` (`npx melchizedek-setup --level oauth-grants` prints this guide)
+
+## 9. Subscription sign-ins (ChatGPT / Codex, Claude.ai, Gemini CLI)
+
+Not supported, on purpose. A consumer subscription sign-in authorizes that vendor's own apps. The engine does not read, reuse or relay those tokens: Anthropic and Google say third-party apps may not use them, and OpenAI's plan-usage sign-in is a preview for approved or locally hosted apps that this engine has not integrated. Use the same vendor's sanctioned route instead.
+
+**Use instead** (names and shapes only):
+
+| Variable | Shape | What it does |
+|---|---|---|
+| `OPENAI_API_KEY` | an API key from https://platform.openai.com/api-keys | instead of a ChatGPT / Codex sign-in (or Azure OpenAI: level 5) |
+| `ANTHROPIC_API_KEY` | an API key from https://console.anthropic.com | instead of a Claude.ai sign-in (or Bedrock / Vertex AI: level 5) |
+| `GOOGLE_GENAI_API_KEY` | an API key from https://aistudio.google.com (free tier) | instead of a Gemini CLI sign-in (or Vertex AI: level 5) |
+
+**Confirm:** `npx melchizedek-doctor`: the provider you chose shows a ✓; nothing reads a subscription sign-in.
+
+**Runs at this level:**
+
+- as level 2 (one key) or level 5 (cloud platform)
+
+**First commands:**
+
+```bash
+npx melchizedek-init --template research_brief
+npx melchizedek-chat --syndicate research_brief
+```
+
+**Notes:**
+
+- Anthropic: Claude.ai (Pro/Max) OAuth is for Claude Code and its own apps; third-party developers may not offer Claude.ai login or route requests through those credentials. Use an API key, Bedrock or Vertex AI.
+- Google: reaching Gemini CLI's services with its sign-in from third-party software is against Gemini CLI's terms. Use an AI Studio key or Vertex AI.
+- OpenAI: an API key or Azure OpenAI. OpenAI's Sign in with ChatGPT plan-usage flow is a documented preview for open-source, locally hosted apps; the engine does not implement it, and reusing the Codex CLI's own token is not that flow.
+- A coding agent signed in with a subscription (Claude Code, Codex, Gemini CLI) can still drive this repository: the sign-in pays for the coding agent, and the engine runs on the keys above.
+
+**Onboarding skill:** `melchizedek-onboard-keys` (`npx melchizedek-setup --level subscription-signin` prints this guide)

package/QUICKSTART.md

@@ -3,6 +3,16 @@
 From zero to a running syndicate in five minutes; to persistent memory in
 fifteen. The full reference is [`DOCUMENTATION.md`](./DOCUMENTATION.md).
 
+**Start with `npx melchizedek-setup`** (in a clone: `npm run setup`). It
+asks what you have (no key, one or several provider keys, a gateway key,
+Vertex AI / Bedrock / Azure access, a server to put in front of others, or
+a ChatGPT, Claude or Gemini sign-in) and prints the startup guide for that
+level: the variables to set (names only; you type the values into `.env`),
+the doctor check, the shipped syndicates that run, and the first command.
+`npm run setup -- --auto` detects your level without printing any value.
+The same guides are in [`ONBOARDING.md`](./ONBOARDING.md); the steps below
+are the two most common paths spelled out.
+
 ## 1. Prerequisites
 
 - **Node.js 22+** (the CLI uses `--experimental-strip-types` to run
@@ -182,6 +192,7 @@ own repo, the same engine is a typed dependency:
 
 ```bash
 npm install melchizedek-agents
+npx melchizedek-setup                        # what you have → the startup guide for it
 npx melchizedek-init                         # config/agents/conversational.yaml + .env; --list for others
 npx melchizedek-doctor                       # which keys it needs, and whether it is ready
 ```
@@ -229,11 +240,13 @@ console.log(result.text);
   section of [`CHANGELOG.md`](./CHANGELOG.md).
   `npx melchizedek-doctor` prints which runtime is in use.
 - **Your coding agent can learn all of this.** The package ships a
-  six-skill suite (`skills/`, the open SKILL.md standard) covering the
-  catalog, authoring, serving, memory, models, and the Scribe:
+  eleven-skill suite (`skills/`, the open SKILL.md standard) covering
+  onboarding (start with `melchizedek-onboard`), the catalog, authoring,
+  serving, memory, models, and the Scribe:
 
   ```bash
   npx melchizedek-skills install          # → .claude/skills + .agents/skills here
+  npx melchizedek-skills install --agents-md   # … and point AGENTS.md at them
   npx melchizedek-skills install --for all --global
   ```
 

package/README.md

@@ -17,12 +17,14 @@ Gemini, Claude, GPT, Grok, and Kimi each run on the engine's own adapter for the
 - **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.
 - **Agent-to-Agent (A2A) serving** — Serve any syndicate over HTTP as a JSON-RPC endpoint with bearer auth and rate limiting.
 - **Knowledge bundle** — `wiki/` documents the framework as an [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog) bundle; `lib/wiki/` builds, lints, and searches any such bundle (`npm run mcp:wiki` serves the tools to MCP clients).
-- **Coding agent skills** — Six skills in the open `SKILL.md` standard for Claude Code, Codex, Cursor, OpenCode, and Gemini CLI.
+- **Coding agent skills** — Eleven skills in the open `SKILL.md` standard for Claude Code, Codex, Cursor, OpenCode, and Gemini CLI, five of them for onboarding a user from whatever credentials they have.
 
 ---
 
 ## Quick Start
 
+Start with `npx melchizedek-setup` (in a clone, `npm run setup`). Tell it what you have (no key, one or several provider keys, a gateway key, Vertex AI / Bedrock / Azure access, a server to put in front of other people, or a ChatGPT, Claude or Gemini sign-in) and it prints the startup guide for that level: which variables to set, the doctor check, which shipped syndicates run, and the first command. `npx melchizedek-setup --auto` detects the level from your environment without printing any value. The guides are also in [ONBOARDING.md](./ONBOARDING.md).
+
 ### 1. Local-only (no API keys)
 
 Prerequisite: install [Ollama](https://ollama.com).
@@ -153,10 +155,11 @@ A Gemini id resolves to the engine's `GeminiAdapter` here, on `@google/genai`.
 
 ### CLI & Server Utilities
 
+- `npx melchizedek-setup`: The onboarding menu: pick what you have, get the startup guide for it (`--auto` detects it).
 - `npx melchizedek-chat --syndicate <name>`: Interactive CLI REPL for any syndicate.
 - `npx melchizedek-serve`: Serve your `./config/agents/` over HTTP via JSON-RPC.
 - `npx melchizedek-doctor`: Report which syndicates your keys unlock, without sending a request.
-- `npx melchizedek-skills install`: Install the agent skills into `.claude/skills/` and `.agents/skills/`.
+- `npx melchizedek-skills install`: Install the agent skills into `.claude/skills/` and `.agents/skills/` (`--agents-md` also points `AGENTS.md` at them).
 
 ---
 

package/config/agents/examples/council.yaml

@@ -34,7 +34,7 @@ orchestrator:
     You are the Moderator of the Council, a small deliberative body that stress-tests claims and plans.
     The user brings a claim, a plan, or a decision they are weighing. You weigh what your two subagents report; you do not research the claim, and you never argue a side yourself.
     TASK: hand back one verdict on the user's claim, in the three-part shape below, built only from the two reports.
-    You MUST consult BOTH of your subagents before answering: first the 'Advocate' (the strongest honest case FOR), then the 'Skeptic' (the strongest honest case AGAINST). Pass each one the user's claim verbatim.
+    You MUST consult BOTH of your subagents before answering, in a single step: call the 'Advocate' (the strongest honest case FOR) and the 'Skeptic' (the strongest honest case AGAINST) together, both function calls in the same response, so they work at once. Pass each one the user's full claim verbatim, never a summary or a part of it.
     Before you write the verdict, decide which single consideration in the two reports weighs most. THE VERDICT names it; the rest of your weighing stays out of the reply.
     Once both reports are in, weigh them and deliver a verdict in exactly this shape:
     - THE CASE FOR: the Advocate's two strongest points, compressed into at most two sentences.

package/config/agents/examples/critic.yaml

@@ -2,14 +2,14 @@
 syndicate_name: "Critic Review Workflow"
 
 # WHY this structure: an agent with an outputSchema answers in that schema and
-# nothing else. On an orchestrator that delegates, the engine (on most
-# models) adds a set_model_response tool beside the subagent tools and the
-# turn ends on the JSON it receives (lib/runtime/native/request.ts), so the
-# user would get the review object instead of the answer; under Google ADK,
-# before 1.0.0, an orchestrator holding both deadlocked. Solution: the
-# orchestrator is a plain sequencer that routes Drafter → Critic, and the
-# CriticAgent (a leaf with no tools and no subagents) owns the outputSchema
-# for structured JSON production.
+# nothing else. An orchestrator that delegates may hold one (ADR 0109): it
+# delegates first, then ends its turn on the JSON, so the user receives the
+# review object itself (structured_critic.yaml is that shape). Here the user
+# should receive the polished answer, not the grading, so the orchestrator
+# is a plain sequencer that routes Drafter → Critic, and the CriticAgent (a
+# leaf with no tools and no subagents) owns the outputSchema the
+# orchestrator's gate reads. The leaf is a choice for this answer, not a
+# rule of the engine.
 #
 # WHY multi-turn internal looping:
 #   The engine's agent loop keeps executing within a single user turn as long

package/config/agents/examples/image_production.yaml

@@ -16,9 +16,10 @@ memory_system: "session-only"
 #   path — the spec physically cannot reach the inventory, so expectation bias
 #   is blocked by the tool signature, not by good intentions. SpecAuditor is a
 #   text-only leaf that receives spec + inventory but never the image, and
-#   holds the outputSchema (the same rule as critic.yaml: the schema-holder
-#   is a leaf that delegates nothing). Perception, judgment, and decision are three
-#   different minds.
+#   holds the outputSchema, so its verdict is JSON while ImageDesigner keeps
+#   answering the user in prose (the same choice as critic.yaml; an
+#   orchestrator may hold a schema itself, ADR 0109, but then its own reply
+#   is the JSON). Perception, judgment, and decision are three different minds.
 #
 # WHY the instruction maps payload fields to tool parameters by name
 # (step 6): the payload holds `meta.artist_style`, the tool takes `style`.

package/config/agents/syndicate.schema.json

@@ -156,7 +156,7 @@
             }
           },
           "additionalProperties": {},
-          "description": "Deprecated v1 spelling (ADR 0115): write `sampling` (temperature, top_p, max_output_tokens, stop), `output.mime` (responseMimeType) and `reasoning` (thinkingConfig, reasoningEffort) instead; npx melchizedek-codemod rewrites a file. Still read: the Gemini GenerateContentConfig shape the engine takes. Do not set tools here.",
+          "description": "Deprecated v1 spelling (ADR 0115): write `sampling` (temperature, top_p, max_output_tokens, stop), `output.mime` (responseMimeType), `reasoning` (thinkingConfig, reasoningEffort) and `tool_choice` (toolConfig.functionCallingConfig) instead; npx melchizedek-codemod rewrites a file. Still read: the Gemini GenerateContentConfig shape the engine takes. Do not set tools here.",
           "deprecated": true
         },
         "reasoning": {
@@ -167,7 +167,9 @@
                 "none",
                 "low",
                 "medium",
-                "high"
+                "high",
+                "xhigh",
+                "max"
               ]
             },
             {
@@ -186,7 +188,7 @@
               "additionalProperties": false
             }
           ],
-          "description": "How hard this agent reasons, on any provider: none | low | medium | high, or { budget_tokens: <int> }. Replaces generateContentConfig.thinkingConfig and reasoningEffort (ADR 0047)."
+          "description": "How hard this agent reasons, on any provider: none | low | medium | high | xhigh | max, or { budget_tokens: <int> }. xhigh and max reach the models that take them; elsewhere they go as the model's highest setting (ADR 0117). Replaces generateContentConfig.thinkingConfig and reasoningEffort (ADR 0047)."
         },
         "sampling": {
           "type": "object",
@@ -242,6 +244,33 @@
           "description": "What this agent's final reply is (ADR 0115). Replaces outputSchema and generateContentConfig.responseMimeType; cannot be combined with them.",
           "minProperties": 1
         },
+        "tool_choice": {
+          "anyOf": [
+            {
+              "type": "string",
+              "enum": [
+                "auto",
+                "none",
+                "required"
+              ]
+            },
+            {
+              "type": "object",
+              "properties": {
+                "name": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "The one tool the model must call: a name from this agent's tools, subagents or MCP tools."
+                }
+              },
+              "required": [
+                "name"
+              ],
+              "additionalProperties": false
+            }
+          ],
+          "description": "Which tools the model may call, on any provider (ADR 0117): 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. Replaces generateContentConfig.toolConfig.functionCallingConfig; cannot be combined with it."
+        },
         "model_overrides": {
           "type": "object",
           "properties": {
@@ -965,7 +994,7 @@
               }
             },
             "additionalProperties": {},
-            "description": "Deprecated v1 spelling (ADR 0115): write `sampling` (temperature, top_p, max_output_tokens, stop), `output.mime` (responseMimeType) and `reasoning` (thinkingConfig, reasoningEffort) instead; npx melchizedek-codemod rewrites a file. Still read: the Gemini GenerateContentConfig shape the engine takes. Do not set tools here.",
+            "description": "Deprecated v1 spelling (ADR 0115): write `sampling` (temperature, top_p, max_output_tokens, stop), `output.mime` (responseMimeType), `reasoning` (thinkingConfig, reasoningEffort) and `tool_choice` (toolConfig.functionCallingConfig) instead; npx melchizedek-codemod rewrites a file. Still read: the Gemini GenerateContentConfig shape the engine takes. Do not set tools here.",
             "deprecated": true
           },
           "reasoning": {
@@ -976,7 +1005,9 @@
                   "none",
                   "low",
                   "medium",
-                  "high"
+                  "high",
+                  "xhigh",
+                  "max"
                 ]
               },
               {
@@ -995,7 +1026,7 @@
                 "additionalProperties": false
               }
             ],
-            "description": "How hard this agent reasons, on any provider: none | low | medium | high, or { budget_tokens: <int> }. Replaces generateContentConfig.thinkingConfig and reasoningEffort (ADR 0047)."
+            "description": "How hard this agent reasons, on any provider: none | low | medium | high | xhigh | max, or { budget_tokens: <int> }. xhigh and max reach the models that take them; elsewhere they go as the model's highest setting (ADR 0117). Replaces generateContentConfig.thinkingConfig and reasoningEffort (ADR 0047)."
           },
           "sampling": {
             "type": "object",
@@ -1051,6 +1082,33 @@
             "description": "What this agent's final reply is (ADR 0115). Replaces outputSchema and generateContentConfig.responseMimeType; cannot be combined with them.",
             "minProperties": 1
           },
+          "tool_choice": {
+            "anyOf": [
+              {
+                "type": "string",
+                "enum": [
+                  "auto",
+                  "none",
+                  "required"
+                ]
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "The one tool the model must call: a name from this agent's tools, subagents or MCP tools."
+                  }
+                },
+                "required": [
+                  "name"
+                ],
+                "additionalProperties": false
+              }
+            ],
+            "description": "Which tools the model may call, on any provider (ADR 0117): 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. Replaces generateContentConfig.toolConfig.functionCallingConfig; cannot be combined with it."
+          },
           "model_overrides": {
             "type": "object",
             "properties": {
@@ -1613,7 +1671,7 @@
             "additionalProperties": false
           },
           "yaml_reference": {
-            "description": "A whole nested syndicate (filename under the agents dir) used as this subagent. An approval request or ask_user question raised inside it pauses the turn with the agent path (ADR 0110, ADR 0111): a delegate syndicate's gates anywhere, a dispatch syndicate's on its classifier (its routes never run nested), and a workflow's ask_user nodes and gates when it is delegated to as a subagent.",
+            "description": "A whole nested syndicate (filename under the agents dir) used as this subagent. An approval request or ask_user question raised inside it pauses the turn with the agent path (ADR 0110, ADR 0111): a delegate syndicate's gates anywhere, a dispatch syndicate's on its routes, which it classifies and runs as at the top, its route's answer being its own (ADR 0120), and a workflow's ask_user nodes and gates, wherever each runs: delegated to as a subagent, as a dispatch route or as a workflow node (ADR 0119).",
             "type": "string",
             "minLength": 1
           },