melchizedek-agents 1.1.0 → 1.2.0

package/dist/scripts/doctor.d.ts

@@ -11,7 +11,9 @@
  * removed that runtime). Lists the tools that need an OAuth grant (an
  * `auth: { oauth2 }` or `mcp_auth`, ADR 0112): each user's consent, or the
  * server's own client credentials and whether their variables are set
- * (names only). Closes with the env vars that would
+ * (names only). When any A2A identity or billing variable is set, a
+ * `serving` line names the A2A_AUTH mode and A2A_KEY_MODE and what the
+ * server would refuse to start on. Closes with the env vars that would
  * unlock the most, where to get each, and the first command to try.
  *
  * Read-only: never edits .env, never sends a request, never prints a key
@@ -20,7 +22,7 @@
  * Usage:
  *   npm run doctor
  *   npm run doctor -- --json          # machine-readable
- *   npm run doctor -- --check         # exit 1 when any syndicate is blocked
+ *   npm run doctor -- --check         # exit 1 on a blocked syndicate, a runtime problem, or an OAuth or credential host problem
  *   npm run doctor -- --matrix        # the provider × capability matrix
  *   npm run doctor -- --fix-namespaces [file…]   # give long-term syndicates a memory_namespace
  *   MELCHIZEDEK_AGENTS_DIR=/path npm run doctor

package/dist/scripts/doctor.js

@@ -11,7 +11,9 @@
  * removed that runtime). Lists the tools that need an OAuth grant (an
  * `auth: { oauth2 }` or `mcp_auth`, ADR 0112): each user's consent, or the
  * server's own client credentials and whether their variables are set
- * (names only). Closes with the env vars that would
+ * (names only). When any A2A identity or billing variable is set, a
+ * `serving` line names the A2A_AUTH mode and A2A_KEY_MODE and what the
+ * server would refuse to start on. Closes with the env vars that would
  * unlock the most, where to get each, and the first command to try.
  *
  * Read-only: never edits .env, never sends a request, never prints a key
@@ -20,7 +22,7 @@
  * Usage:
  *   npm run doctor
  *   npm run doctor -- --json          # machine-readable
- *   npm run doctor -- --check         # exit 1 when any syndicate is blocked
+ *   npm run doctor -- --check         # exit 1 on a blocked syndicate, a runtime problem, or an OAuth or credential host problem
  *   npm run doctor -- --matrix        # the provider × capability matrix
  *   npm run doctor -- --fix-namespaces [file…]   # give long-term syndicates a memory_namespace
  *   MELCHIZEDEK_AGENTS_DIR=/path npm run doctor
@@ -28,7 +30,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { loadEnv } from '../lib/loadEnv.js';
-import { renderDoctor, runDoctor } from '../lib/doctor.js';
+import { checkProblems, renderDoctor, runDoctor } from '../lib/doctor.js';
 import { renderCapabilityMatrix } from '../lib/models/capabilities.js';
 import { assignMemoryNamespace, LEGACY_MEMORY_APP_NAME } from '../lib/memory/namespace.js';
 loadEnv();
@@ -91,5 +93,5 @@ if (json) {
 else {
     console.log(renderDoctor(result, { color: !noColor }));
 }
-if (check && (result.counts.blocked > 0 || result.runtime.problem || result.oauth?.problems.length))
+if (check && checkProblems(result).length)
     process.exit(1);

package/dist/scripts/setup.d.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/**
+ * scripts/setup.ts — the `melchizedek-setup` bin and `npm run setup`.
+ *
+ * The onboarding command: a menu of authentication levels (no key, one
+ * provider, several, a gateway, a cloud platform, per-caller keys, caller
+ * tokens, OAuth tool grants, and an honest entry for subscription sign-ins),
+ * each with a startup guide: the variables to set (names and shapes only),
+ * the doctor command that confirms it, the shipped files that run there and
+ * the first commands to try. The levels and guides live in lib/onboarding.ts;
+ * ONBOARDING.md is generated from the same function.
+ *
+ *   npx melchizedek-setup                     # the menu (interactive terminal)
+ *   npx melchizedek-setup --auto              # detect from the environment, names only
+ *   npx melchizedek-setup --level gateway     # one guide, by id or number
+ *   npx melchizedek-setup --level 2 --write-env   # also create .env from .env.example
+ *   npx melchizedek-setup --list
+ *   npx melchizedek-setup --markdown          # ONBOARDING.md, regenerated
+ *
+ * Never prints a value. `--write-env` never overwrites `.env`, leaves every
+ * name blank, and refuses unless `git check-ignore` confirms `.env` is ignored.
+ */
+export declare function main(argv?: string[]): Promise<number>;

package/dist/scripts/setup.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+/**
+ * scripts/setup.ts — the `melchizedek-setup` bin and `npm run setup`.
+ *
+ * The onboarding command: a menu of authentication levels (no key, one
+ * provider, several, a gateway, a cloud platform, per-caller keys, caller
+ * tokens, OAuth tool grants, and an honest entry for subscription sign-ins),
+ * each with a startup guide: the variables to set (names and shapes only),
+ * the doctor command that confirms it, the shipped files that run there and
+ * the first commands to try. The levels and guides live in lib/onboarding.ts;
+ * ONBOARDING.md is generated from the same function.
+ *
+ *   npx melchizedek-setup                     # the menu (interactive terminal)
+ *   npx melchizedek-setup --auto              # detect from the environment, names only
+ *   npx melchizedek-setup --level gateway     # one guide, by id or number
+ *   npx melchizedek-setup --level 2 --write-env   # also create .env from .env.example
+ *   npx melchizedek-setup --list
+ *   npx melchizedek-setup --markdown          # ONBOARDING.md, regenerated
+ *
+ * Never prints a value. `--write-env` never overwrites `.env`, leaves every
+ * name blank, and refuses unless `git check-ignore` confirms `.env` is ignored.
+ */
+import { realpathSync } from 'node:fs';
+import { createInterface } from 'node:readline/promises';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { loadEnv } from '../lib/loadEnv.js';
+import { runDoctor } from '../lib/doctor.js';
+import { detectLevels, highestLevel, LEVELS, levelById, renderAuto, renderGuide, renderMenu, renderOnboardingDoc, writeEnvForLevel, } from '../lib/onboarding.js';
+const USAGE = `melchizedek-setup — start from what you have
+
+  melchizedek-setup                       the menu of authentication levels
+  melchizedek-setup --auto                detect the highest level from the environment (names only)
+  melchizedek-setup --level <id|number>   print one level's startup guide
+  melchizedek-setup --list                the levels
+  melchizedek-setup --markdown            every guide as Markdown (ONBOARDING.md)
+
+  --write-env   with --level or --auto: create .env from .env.example with the level's
+                names left blank (never overwrites; requires git to ignore .env)
+  --clone | --package   spell commands for a clone or an installed package (default: detected)
+
+Levels:
+${renderMenu()}
+`;
+function pickLevel(raw) {
+    const n = Number(raw);
+    if (Number.isInteger(n) && n >= 1 && n <= LEVELS.length)
+        return LEVELS[n - 1];
+    return levelById(raw.trim());
+}
+function writeEnv(level) {
+    const r = writeEnvForLevel(level);
+    switch (r.status) {
+        case 'written':
+            console.log(`\n✓ wrote ${r.path} (mode 600) from .env.example${r.added.length ? `, adding blank: ${r.added.join(', ')}` : ''}. Fill in the values yourself, in your editor.`);
+            return 0;
+        case 'exists':
+            console.log(`\n· kept ${r.path}: it exists, and setup never overwrites it. Add the names above to it yourself.`);
+            return 0;
+        case 'not-ignored':
+            console.error(`\n✗ did not write .env: ${r.reason}`);
+            return 1;
+        case 'no-template':
+            console.error('\n✗ did not write .env: .env.example was not found beside the package');
+            return 1;
+    }
+}
+export async function main(argv = process.argv.slice(2)) {
+    const args = argv.filter((a) => a !== '--');
+    const flag = (name) => {
+        const i = args.indexOf(`--${name}`);
+        return i >= 0 && i + 1 < args.length ? args[i + 1] : undefined;
+    };
+    const inPackage = fileURLToPath(import.meta.url).includes('node_modules');
+    const form = args.includes('--clone') ? 'clone' : args.includes('--package') ? 'package' : inPackage ? 'package' : 'clone';
+    if (args.includes('--help') || args.includes('-h')) {
+        console.log(USAGE);
+        return 0;
+    }
+    if (args.includes('--list')) {
+        console.log(renderMenu());
+        return 0;
+    }
+    if (args.includes('--markdown')) {
+        process.stdout.write(renderOnboardingDoc());
+        return 0;
+    }
+    let level;
+    if (args.includes('--auto')) {
+        loadEnv();
+        const result = runDoctor();
+        console.log(renderAuto(result, form));
+        if (!args.includes('--write-env'))
+            return 0;
+        return writeEnv(highestLevel(detectLevels(result)));
+    }
+    const raw = flag('level');
+    if (raw !== undefined) {
+        level = pickLevel(raw);
+        if (!level) {
+            console.error(`✗ unknown level "${raw}"\n\n${USAGE}`);
+            return 2;
+        }
+        console.log(renderGuide(level, form));
+        return args.includes('--write-env') ? writeEnv(level) : 0;
+    }
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        console.log(USAGE);
+        return 0;
+    }
+    // The interactive menu.
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        console.log(`What do you have? Pick the closest; you can come back for another.\n\n${renderMenu()}\n`);
+        const answer = (await rl.question(`Level [1-${LEVELS.length}], a = detect from my environment, q = quit: `)).trim().toLowerCase();
+        if (answer === 'q' || answer === '')
+            return 0;
+        if (answer === 'a') {
+            loadEnv();
+            console.log(`\n${renderAuto(runDoctor(), form)}`);
+            return 0;
+        }
+        level = pickLevel(answer);
+        if (!level) {
+            console.error(`✗ "${answer}" is not a level`);
+            return 2;
+        }
+        console.log(`\n${renderGuide(level, form)}\n`);
+        if (level.detectable) {
+            const write = (await rl.question('Create .env from .env.example with these names left blank? (never overwrites) [y/N]: ')).trim().toLowerCase();
+            if (write === 'y' || write === 'yes')
+                return writeEnv(level);
+        }
+        return 0;
+    }
+    finally {
+        rl.close();
+    }
+}
+const invokedAsMain = (() => {
+    if (!process.argv[1])
+        return false;
+    try {
+        return import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+    }
+    catch {
+        return false;
+    }
+})();
+if (invokedAsMain) {
+    main().then((code) => process.exit(code), (err) => {
+        console.error(`✗ ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    });
+}

package/dist/scripts/skills_install.d.ts

@@ -2,6 +2,8 @@
 import { type InstallOptions } from '../lib/skills.ts';
 export declare function parseArgs(argv: string[]): {
     command: string;
-    opts: InstallOptions;
+    opts: InstallOptions & {
+        agentsMd?: boolean;
+    };
 };
 export declare function main(argv?: string[]): number;

package/dist/scripts/skills_install.js

@@ -16,6 +16,7 @@
  *   melchizedek-skills install --only melchizedek,melchizedek-scribe
  *   melchizedek-skills install --force      # overwrite files that differ
  *   melchizedek-skills install --dry-run
+ *   melchizedek-skills install --agents-md  # also point AGENTS.md at the skills
  *
  * Clone equivalent: npm run skills:install -- <same flags>.
  * Nothing is read from the network; nothing is written outside the chosen
@@ -23,12 +24,12 @@
  */
 import { realpathSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
-import { DEFAULT_TARGETS, SKILL_TARGETS, destinationsFor, installSkills, listSkills, } from '../lib/skills.js';
+import { DEFAULT_TARGETS, SKILL_TARGETS, destinationsFor, installSkills, listSkills, writeAgentsMdPointer, } from '../lib/skills.js';
 const USAGE = `melchizedek-skills — install the Melchizedek agent-skills suite into your coding agent
 
   melchizedek-skills list
   melchizedek-skills paths
-  melchizedek-skills install [--for <targets>] [--global] [--dir <path>] [--only <skills>] [--force] [--dry-run]
+  melchizedek-skills install [--for <targets>] [--global] [--dir <path>] [--only <skills>] [--force] [--dry-run] [--agents-md]
 
   --for      comma list of: ${Object.keys(SKILL_TARGETS).join(', ')}, all   (default: ${DEFAULT_TARGETS.join(',')})
   --global   write to the home-directory locations instead of this project's
@@ -36,6 +37,10 @@ const USAGE = `melchizedek-skills — install the Melchizedek agent-skills suite
   --only     comma list of skill names (default: every skill)
   --force    overwrite a file that exists with different content
   --dry-run  print what would be written, write nothing
+  --agents-md  also write a pointer block into ./AGENTS.md (created if absent; only the
+             block between its markers is ever rewritten). Project installs only.
+
+Onboarding starts with the melchizedek-onboard skill, or: npx melchizedek-setup
 `;
 export function parseArgs(argv) {
     const [command = 'help', ...rest] = argv.filter((a) => a !== '--');
@@ -62,6 +67,8 @@ export function parseArgs(argv) {
             opts.force = true;
         else if (a === '--dry-run')
             opts.dryRun = true;
+        else if (a === '--agents-md')
+            opts.agentsMd = true;
         else if (a === '-h' || a === '--help')
             return { command: 'help', opts };
         else
@@ -117,6 +124,14 @@ export function main(argv = process.argv.slice(2)) {
         for (const f of r.skipped)
             console.log(`    ! ${f} exists with different content (use --force to overwrite)`);
     }
+    if (opts.agentsMd) {
+        if (opts.global || opts.dir) {
+            console.error('✗ --agents-md writes ./AGENTS.md beside a project install; it is not used with --global or --dir');
+            return 2;
+        }
+        const r = writeAgentsMdPointer(process.cwd(), destinationsFor(opts), { dryRun: opts.dryRun });
+        console.log(`${opts.dryRun ? '○' : '✓'} ${r.path}: ${r.status}${opts.dryRun ? ' (dry run)' : ''}`);
+    }
     if (!opts.dir) {
         const sample = destinationsFor(opts);
         console.log(`\nOpen your coding agent in ${opts.global ? 'any project' : 'this project'} and ask it about a Melchizedek syndicate; the skills load from ${sample.map((d) => d).join(' and ')}.`);

package/dist/scripts/yaml_codemod.d.ts

@@ -19,8 +19,18 @@
  *   generateContentConfig.thinkingConfig / reasoningEffort → reasoning:, ONLY
  *     when the engine reads the same ReasoningSetting before and after for
  *     the agent's model (reasoningOf over the old config equals reasoningOf
- *     over what reasoningConfig makes of the new key).
- *   generateContentConfig.thinkingConfig.includeThoughts: false → dropped (the default; read by nothing)
+ *     over what reasoningConfig makes of the new key). `xhigh` and `max`
+ *     included (ADR 0117).
+ *   generateContentConfig.thinkingConfig.includeThoughts → dropped: the
+ *     engine reads it nowhere, and the Gemini adapter asks for the thought
+ *     trace itself whenever reasoning is not `none` (ADR 0117); `true` gets a
+ *     note saying so.
+ *   generateContentConfig.toolConfig → tool_choice: (ADR 0117), when it holds
+ *     only functionCallingConfig (mode AUTO, NONE or ANY, and
+ *     allowedFunctionNames) and includeServerSideToolInvocations, which the
+ *     compiler sets on every agent: AUTO is `auto`, NONE `none`, ANY with
+ *     one name `{ name }`, and ANY with none or several `required`, which is
+ *     what the engine reads (genaiMapping toolChoiceOf) either way.
  *
  * Anything else stays under generateContentConfig with a note naming its key
  * path (never its value); an emptied generateContentConfig is removed. An

package/dist/scripts/yaml_codemod.js

@@ -19,8 +19,18 @@
  *   generateContentConfig.thinkingConfig / reasoningEffort → reasoning:, ONLY
  *     when the engine reads the same ReasoningSetting before and after for
  *     the agent's model (reasoningOf over the old config equals reasoningOf
- *     over what reasoningConfig makes of the new key).
- *   generateContentConfig.thinkingConfig.includeThoughts: false → dropped (the default; read by nothing)
+ *     over what reasoningConfig makes of the new key). `xhigh` and `max`
+ *     included (ADR 0117).
+ *   generateContentConfig.thinkingConfig.includeThoughts → dropped: the
+ *     engine reads it nowhere, and the Gemini adapter asks for the thought
+ *     trace itself whenever reasoning is not `none` (ADR 0117); `true` gets a
+ *     note saying so.
+ *   generateContentConfig.toolConfig → tool_choice: (ADR 0117), when it holds
+ *     only functionCallingConfig (mode AUTO, NONE or ANY, and
+ *     allowedFunctionNames) and includeServerSideToolInvocations, which the
+ *     compiler sets on every agent: AUTO is `auto`, NONE `none`, ANY with
+ *     one name `{ name }`, and ANY with none or several `required`, which is
+ *     what the engine reads (genaiMapping toolChoiceOf) either way.
  *
  * Anything else stays under generateContentConfig with a note naming its key
  * path (never its value); an emptied generateContentConfig is removed. An
@@ -41,7 +51,8 @@ import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { isDeepStrictEqual } from 'node:util';
 import { isMap, isPair, isScalar, isSeq, parseDocument } from 'yaml';
-import { reasoningOf } from '../lib/models/genaiMapping.js';
+import { functionCallingConfigOf } from '../lib/agentDialect.js';
+import { reasoningOf, toolChoiceOf } from '../lib/models/genaiMapping.js';
 import { reasoningConfig } from '../lib/models/reasoning.js';
 /** generateContentConfig keys with a `sampling:` form, and the check its value must pass. */
 const SAMPLING = new Map([
@@ -51,9 +62,11 @@ const SAMPLING = new Map([
     ['stopSequences', { key: 'stop', ok: (v) => Array.isArray(v) && v.length > 0 && v.every((s) => typeof s === 'string') }],
 ]);
 const OUTPUT_MIMES = new Set(['application/json', 'text/plain']);
-const THINKING_LEVEL = new Map([['MINIMAL', 'none'], ['LOW', 'low'], ['MEDIUM', 'medium'], ['HIGH', 'high']]);
-const EFFORT_WORD = new Map([['none', 'none'], ['minimal', 'none'], ['low', 'low'], ['medium', 'medium'], ['high', 'high']]);
 const THINKING_KEYS = new Set(['thinkingLevel', 'thinkingBudget', 'includeThoughts']);
+/** toolConfig keys the codemod can account for: the choice, and the flag the compiler sets on every agent. */
+const TOOL_CONFIG_KEYS = new Set(['functionCallingConfig', 'includeServerSideToolInvocations']);
+const FUNCTION_CALLING_KEYS = new Set(['mode', 'allowedFunctionNames']);
+const FUNCTION_CALLING_MODES = new Set(['AUTO', 'NONE', 'ANY']);
 // ── The source, by line ──────────────────────────────────────────────────────
 class Source {
     text;
@@ -256,11 +269,17 @@ function planAgent(doc, src, map, path, notes) {
             const re = chunks.find((c) => c.name === 'reasoningEffort');
             if (tc || re)
                 planThinking(plan, map, tc, re, valueOf, notes);
+            // Tool choice.
+            const toolConfig = chunks.find((c) => c.name === 'toolConfig');
+            if (toolConfig)
+                planToolChoice(plan, map, toolConfig, valueOf(toolConfig), notes);
             // Leftovers: everything not moved, converted or dropped.
             const handled = new Set([...plan.sampling, ...(plan.mime ? [plan.mime] : []), ...(plan.reasoning?.remove ?? [])]);
             if (plan.dropInclude?.empties)
                 handled.add(plan.dropInclude.tc);
-            const noted = new Set(['thinkingConfig', 'reasoningEffort', 'responseMimeType', ...SAMPLING.keys()]);
+            if (plan.toolChoice)
+                handled.add(plan.toolChoice.chunk);
+            const noted = new Set(['thinkingConfig', 'reasoningEffort', 'responseMimeType', 'toolConfig', ...SAMPLING.keys()]);
             for (const c of chunks) {
                 if (handled.has(c) || noted.has(c.name))
                     continue;
@@ -268,27 +287,74 @@ function planAgent(doc, src, map, path, notes) {
             }
         }
     }
-    const changes = plan.sampling.length > 0 || plan.mime || plan.schema || plan.reasoning || plan.dropInclude;
+    const changes = plan.sampling.length > 0 || plan.mime || plan.schema || plan.reasoning || plan.dropInclude || plan.toolChoice;
     return changes ? plan : undefined;
 }
+/**
+ * toolConfig → tool_choice, when the engine reads the same ToolChoice before
+ * and after (genaiMapping toolChoiceOf) and nothing else in it would be lost.
+ */
+function planToolChoice(plan, map, chunk, value, notes) {
+    const where = `${plan.path}.generateContentConfig.toolConfig`;
+    const leave = (why) => {
+        notes.push(`${where}: ${why}; left in place`);
+    };
+    if (findPair(map, 'tool_choice'))
+        return leave(`${plan.path}.tool_choice is already set (the loader refuses both)`);
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return leave('not a mapping');
+    const tc = value;
+    if (Object.keys(tc).some((k) => !TOOL_CONFIG_KEYS.has(k)))
+        return leave('it holds a key with no v2 form');
+    const fcc = tc.functionCallingConfig;
+    if (fcc !== undefined) {
+        if (!fcc || typeof fcc !== 'object' || Array.isArray(fcc))
+            return leave('functionCallingConfig is not a mapping');
+        const f = fcc;
+        if (Object.keys(f).some((k) => !FUNCTION_CALLING_KEYS.has(k)))
+            return leave('functionCallingConfig holds a key with no tool_choice form');
+        if (f.mode === 'VALIDATED')
+            return leave('mode VALIDATED (strict tool schemas) has no tool_choice form');
+        if (!FUNCTION_CALLING_MODES.has(f.mode))
+            return leave('its mode is not AUTO, NONE or ANY');
+        const names = f.allowedFunctionNames;
+        if (names !== undefined && !(Array.isArray(names) && names.every((n) => typeof n === 'string')))
+            return leave('allowedFunctionNames is not a list of names');
+        if (f.mode === 'ANY' && Array.isArray(names) && names.length > 1) {
+            notes.push(`${where}.functionCallingConfig.allowedFunctionNames: several names, which the engine sends as required (any tool); tool_choice: required says the same`);
+        }
+    }
+    // What the engine reads today is the v2 setting; the proof is that the v2
+    // key's engine form reads back the same.
+    const before = toolChoiceOf({ toolConfig: tc });
+    const setting = before.toolChoice ?? 'auto';
+    const after = toolChoiceOf({ toolConfig: { functionCallingConfig: functionCallingConfigOf(setting) } });
+    if (!isDeepStrictEqual(before, after))
+        return leave('tool_choice: would change what the engine reads');
+    plan.toolChoice = { setting, chunk };
+}
 function planThinking(plan, map, tc, re, valueOf, notes) {
     const gccPath = `${plan.path}.generateContentConfig`;
     const where = [tc, re].filter((c) => !!c).map((c) => `${gccPath}.${c.name}`).join(', ');
     const tcValue = tc ? valueOf(tc) : undefined;
     const tcObject = tcValue && typeof tcValue === 'object' && !Array.isArray(tcValue) ? tcValue : undefined;
     const model = scalarString(map, 'model');
-    // includeThoughts: false is the default and read by nothing: drop it from a
-    // block thinkingConfig whatever else happens to the thinking keys.
+    // includeThoughts is read by nothing: the Gemini adapter asks for the
+    // thought trace whenever reasoning is not `none` (ADR 0117). Drop it from
+    // a block thinkingConfig whatever else happens to the thinking keys.
     const incPair = tc && isMap(tc.pair.value) && !tc.pair.value.flow ? findPair(tc.pair.value, 'includeThoughts') : undefined;
-    const incFalse = incPair && isScalar(incPair.value) && incPair.value.value === false;
+    const incValue = incPair && isScalar(incPair.value) ? incPair.value.value : undefined;
+    const incBool = typeof incValue === 'boolean';
+    if (incValue === true) {
+        notes.push(`${gccPath}.thinkingConfig.includeThoughts: read by nothing (the Gemini adapter asks for the thought trace whenever reasoning is not none); dropped`);
+    }
+    const dropInclude = () => {
+        if (tc && incBool)
+            plan.dropInclude = { tc, inc: incPair, empties: tc.pair.value.items.length === 1 };
+    };
     const leave = (why) => {
         notes.push(`${where}: ${why}; left in place`);
-        if (tc && incFalse) {
-            const tcMap = tc.pair.value;
-            plan.dropInclude = { tc, inc: incPair, empties: tcMap.items.length === 1 };
-        }
-        if (tcObject?.includeThoughts === true)
-            notes.push(`${gccPath}.thinkingConfig.includeThoughts: no v2 form; left in place`);
+        dropInclude();
     };
     if (findPair(map, 'reasoning'))
         return leave(`${plan.path}.reasoning is already set (the loader refuses both)`);
@@ -298,35 +364,39 @@ function planThinking(plan, map, tc, re, valueOf, notes) {
         return leave('thinkingConfig is not a mapping');
     if (tcObject && Object.keys(tcObject).some((k) => !THINKING_KEYS.has(k)))
         return leave('thinkingConfig holds a key with no reasoning: form');
-    if (tcObject && tcObject.includeThoughts !== undefined && tcObject.includeThoughts !== false)
-        return leave('includeThoughts has no reasoning: form');
     const v1 = {};
     if (tc)
         v1.thinkingConfig = tcValue;
     if (re)
         v1.reasoningEffort = valueOf(re);
-    let candidate;
-    const level = THINKING_LEVEL.get(tcObject?.thinkingLevel);
-    const budget = tcObject?.thinkingBudget;
-    if (level)
-        candidate = level;
-    else if (typeof budget === 'number' && Number.isInteger(budget) && budget >= 0)
-        candidate = { budget_tokens: budget };
-    else if (EFFORT_WORD.has(v1.reasoningEffort))
-        candidate = EFFORT_WORD.get(v1.reasoningEffort);
-    if (candidate === undefined)
-        return leave('no reasoning: setting reads the same');
+    // The setting is what the engine reads today; it converts when the v2
+    // key's engine form reads back the same for the agent's model.
     const before = reasoningOf(v1);
-    const after = reasoningOf(reasoningConfig(model, candidate));
+    if (before === undefined) {
+        // A thinkingConfig holding includeThoughts alone: nothing to convert, and nothing left.
+        if (!re && tcObject && Object.keys(tcObject).every((k) => k === 'includeThoughts'))
+            return dropInclude();
+        return leave('no reasoning: setting reads the same');
+    }
+    const after = reasoningOf(reasoningConfig(model, before));
     if (!isDeepStrictEqual(before, after))
         return leave(`reasoning: would change what the engine reads for ${providerWord(model)}`);
-    plan.reasoning = { setting: candidate, remove: [tc, re].filter((c) => !!c) };
+    plan.reasoning = { setting: before, remove: [tc, re].filter((c) => !!c) };
 }
 /** A model family word for a note: never the id's value beyond its prefix. */
 function providerWord(model) {
     return model.startsWith('gemini-') ? 'this Gemini model' : 'this model';
 }
 const reasoningText = (s) => (typeof s === 'string' ? s : `{ budget_tokens: ${s.budget_tokens} }`);
+/** A tool name YAML reads back as that string unquoted: an identifier that is not a YAML keyword. */
+const PLAIN_NAME = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+const YAML_WORDS = new Set(['true', 'false', 'null', 'yes', 'no', 'on', 'off', 'y', 'n']);
+const toolChoiceText = (s) => {
+    if (typeof s === 'string')
+        return s;
+    const plain = PLAIN_NAME.test(s.name) && !YAML_WORDS.has(s.name.toLowerCase());
+    return `{ name: ${plain ? s.name : JSON.stringify(s.name)} }`;
+};
 function chunkLines(src, c) {
     return src.lines.slice(c.from, c.to + 1);
 }
@@ -343,12 +413,14 @@ function renderGcc(src, plan) {
     const g = plan.gcc;
     if (!g)
         return undefined;
-    if (!(plan.sampling.length || plan.mime || plan.reasoning || plan.dropInclude))
+    if (!(plan.sampling.length || plan.mime || plan.reasoning || plan.dropInclude || plan.toolChoice))
         return undefined;
     const pad = ' '.repeat(g.indent);
     const removed = new Set([...plan.sampling, ...(plan.mime ? [plan.mime] : []), ...(plan.reasoning?.remove ?? [])]);
     if (plan.dropInclude?.empties)
         removed.add(plan.dropInclude.tc);
+    if (plan.toolChoice)
+        removed.add(plan.toolChoice.chunk);
     const leftovers = g.chunks.filter((c) => !removed.has(c));
     const out = [];
     if (leftovers.length === 0) {
@@ -367,6 +439,12 @@ function renderGcc(src, plan) {
                 out.push(pad + comment);
         out.push(`${pad}reasoning: ${reasoningText(plan.reasoning.setting)}`);
     }
+    if (plan.toolChoice) {
+        const c = plan.toolChoice.chunk;
+        for (const comment of commentsIn(src, c.from, c.to, c.pair))
+            out.push(pad + comment);
+        out.push(`${pad}tool_choice: ${toolChoiceText(plan.toolChoice.setting)}`);
+    }
     if (plan.mime && !plan.schema) {
         out.push(`${pad}output:`);
         out.push(...renamed(src, plan.mime, 'mime'));
@@ -444,6 +522,10 @@ function expectAgent(agent, plan) {
             delete gcc[c.name];
         agent.reasoning = plan.reasoning.setting;
     }
+    if (plan.toolChoice) {
+        delete gcc.toolConfig;
+        agent.tool_choice = plan.toolChoice.setting;
+    }
     if (plan.dropInclude) {
         const tc = gcc.thinkingConfig;
         delete tc.includeThoughts;
@@ -522,7 +604,7 @@ function yamlFiles(path) {
 }
 const USAGE = `usage: yaml_codemod [--check] <file|dir>...
   Rewrites agent v1 spellings (generateContentConfig, outputSchema) into the
-  v2 keys (sampling, output, reasoning), in place. A directory means every
+  v2 keys (sampling, output, reasoning, tool_choice), in place. A directory means every
   *.yaml below it. --check writes nothing and exits 1 if any file would change.`;
 export function main(argv) {
     const check = argv.includes('--check');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "melchizedek-agents",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "A multi-model, multi-agent orchestration framework — YAML-defined syndicates on the engine's own agent loop, Supabase or Postgres session persistence, pgvector long-term memory. Companion repo to the lyceumagents.com curriculum.",
   "type": "module",
   "license": "MIT",
@@ -54,6 +54,7 @@
     "melchizedek-worker": "./dist/scripts/assistant_worker.js",
     "melchizedek-db": "./dist/scripts/db.js",
     "melchizedek-init": "./dist/scripts/init.js",
+    "melchizedek-setup": "./dist/scripts/setup.js",
     "melchizedek-registry": "./dist/scripts/registry.js",
     "melchizedek-codemod": "./dist/scripts/yaml_codemod.js"
   },
@@ -69,6 +70,7 @@
     ".env.example",
     "CHANGELOG.md",
     "QUICKSTART.md",
+    "ONBOARDING.md",
     "DOCUMENTATION.md",
     "AGENT_SETUP.md",
     "skills"
@@ -117,6 +119,7 @@
     "yaml:codemod": "node --disable-warning=DEP0040 --experimental-strip-types scripts/yaml_codemod.ts",
     "start:a2a": "node --disable-warning=DEP0040 --experimental-strip-types scripts/a2a_server.ts",
     "test": "node --disable-warning=DEP0040 --experimental-strip-types --test tests/**/*.test.ts",
+    "setup": "node --disable-warning=DEP0040 --experimental-strip-types scripts/setup.ts",
     "init": "node --disable-warning=DEP0040 --experimental-strip-types scripts/init.ts",
     "db": "node --disable-warning=DEP0040 --experimental-strip-types scripts/db.ts",
     "registry": "node --disable-warning=DEP0040 --experimental-strip-types scripts/registry.ts",

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 nine 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, and the honest answer for a ChatGPT / 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.