@nodeint/migent 0.1.6 → 0.1.8

package/dist/display.js

@@ -41,6 +41,8 @@ export function printDoctor(checks) {
         }
         for (const problem of check.problems)
             process.stdout.write(`  ${problem}\n`);
+        for (const warning of check.warnings)
+            process.stdout.write(`  warning: ${warning}\n`);
     }
 }
 export function printSessions(rows) {
@@ -50,7 +52,8 @@ export function printSessions(rows) {
     }
     for (const row of rows) {
         const fields = sessionFields(row);
-        process.stdout.write(`${fields.session}  ${fields.workflow}  ${fields.status}  ${fields.execution}  ${fields.decision}  ${fields.outputs}  ${fields.task}\n`);
+        const identity = fields.title !== "" && fields.title !== fields.session ? `${fields.title}  ${fields.session}` : fields.session;
+        process.stdout.write(`${identity}  ${fields.workflow}  ${fields.status}  ${fields.execution}  ${fields.decision}  ${fields.outputs}  ${fields.task}\n`);
     }
 }
 export function printAgent(result, role, provider, model) {
@@ -73,6 +76,10 @@ export function printWatchSnapshot(snapshot) {
         ["session_id", String(snapshot.session_id ?? "--")],
         ["status", String(snapshot.status ?? "unknown")],
     ];
+    const title = snapshot.title;
+    if (typeof title === "string" && title !== "" && title !== lines[0]?.[1]) {
+        lines.splice(1, 0, ["title", title]);
+    }
     if (typeof snapshot.workflow_id === "string" && snapshot.workflow_id) {
         lines.push(["workflow", snapshot.workflow_id]);
     }
@@ -133,6 +140,40 @@ export function formatWatchTimestamp(timestamp) {
         return timestamp.trim();
     return parsed.toISOString().replace("T", " ").replace(/\.\d+Z$/, "+00:00").replace("Z", "+00:00");
 }
+export function printProviders(rows) {
+    const tty = Boolean(process.stdout.isTTY);
+    for (const row of rows) {
+        const ok = row.problems.length === 0 && row.models.length > 0;
+        const status = ok ? (tty ? pc.green("ok") : "ok") : tty ? pc.red("failed") : "failed";
+        process.stdout.write(`${row.name.padEnd(12)}${status}\n`);
+        if (row.path !== null) {
+            const line = `  path: ${row.path}`;
+            process.stdout.write(`${tty ? pc.dim(line) : line}\n`);
+        }
+        else {
+            const line = `  path: not found`;
+            process.stdout.write(`${tty ? pc.dim(line) : line}\n`);
+        }
+        if (row.models.length > 0) {
+            process.stdout.write(`  models:\n`);
+            for (const model of row.models) {
+                const marked = model === row.default_model ? `${model} (default)` : model;
+                const line = `    ${marked}`;
+                process.stdout.write(`${tty ? pc.dim(line) : line}\n`);
+            }
+        }
+        if (row.options.length > 0) {
+            process.stdout.write(`  options:\n`);
+            for (const opt of row.options) {
+                const line = `    ${opt.name}`;
+                process.stdout.write(`${tty ? pc.dim(line) : line}\n`);
+            }
+        }
+        for (const problem of row.problems) {
+            process.stdout.write(`  ${problem}\n`);
+        }
+    }
+}
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/dist/hooks.d.ts

@@ -1,6 +1,8 @@
 import type { AgentToolRunner } from "@nodeint/migent-kernel";
+import type { RunCommand } from "./provider.js";
 /** Test seams. Production leaves both null. */
 export declare const cliHooks: {
     which: ((command: string) => string | null) | null;
     runner: AgentToolRunner | null;
+    runCommand: RunCommand | null;
 };

package/dist/hooks.js

@@ -2,4 +2,5 @@
 export const cliHooks = {
     which: null,
     runner: null,
+    runCommand: null,
 };

package/dist/index.js

@@ -36,6 +36,7 @@ export async function main(argv = process.argv.slice(2), cwd) {
         setInvocationCwd(undefined);
         cliHooks.which = null;
         cliHooks.runner = null;
+        cliHooks.runCommand = null;
     }
 }
 function isDirectRun() {

package/dist/migrate.d.ts

@@ -1,8 +1,8 @@
-import { type MigrationAdapter } from "@nodeint/migent-kernel";
+import { type MigrationProvider } from "@nodeint/migent-kernel";
 export declare function requireCurrentSchema(workspace: string): void;
 export declare function runMigrate(workspace: string, options?: {
     assumeYes?: boolean;
     confirm?: ((message: string) => boolean | Promise<boolean>) | null;
-    adapters?: Record<string, MigrationAdapter> | null;
+    providers?: Record<string, MigrationProvider> | null;
 }): Promise<number>;
-export declare function migrationAdapters(adapters?: Record<string, unknown>): Record<string, MigrationAdapter>;
+export declare function migrationProviders(providers?: Record<string, unknown>): Record<string, MigrationProvider>;

package/dist/migrate.js

@@ -4,29 +4,31 @@ import { confirm as clackConfirm, isCancel } from "@clack/prompts";
 import { SCHEMA_VERSION, documentVersion, loadYamlMapping, migrateConfig, migrateWorkflow, patchConfigText, patchWorkflowText, workflowsDirectory, ConfigurationError, } from "@nodeint/migent-kernel";
 import { printError, printNotice } from "./display.js";
 import { isDirectory, isFile } from "./fs-utils.js";
-import { adapterMap } from "./provider.js";
-const OUTDATED = "Schema is outdated. Run `migent migrate` to update.";
+import { providerMap } from "./provider.js";
+function versionList(entries) {
+    const width = Math.max(...entries.map(([label]) => label.length));
+    return entries.map(([label, version]) => `  ${label.padEnd(width)}  v${version}`).join("\n");
+}
 export function requireCurrentSchema(workspace) {
     const newer = [];
-    let outdated = false;
+    const older = [];
     for (const [label, filePath] of schemaFiles(workspace)) {
         const version = storedVersion(filePath);
         if (version === null || version === SCHEMA_VERSION)
             continue;
-        if (version > SCHEMA_VERSION) {
-            newer.push(`${label} schema_version ${version} is newer than this Migent (${SCHEMA_VERSION}).`);
-            continue;
-        }
-        outdated = true;
+        (version > SCHEMA_VERSION ? newer : older).push([label, version]);
+    }
+    if (older.length > 0) {
+        throw new ConfigurationError(`Schema is outdated (this Migent uses v${SCHEMA_VERSION}).\n${versionList(older)}\n\n` +
+            "Run `migent migrate` to update.");
+    }
+    if (newer.length > 0) {
+        throw new ConfigurationError(`Schema is newer than this Migent supports (v${SCHEMA_VERSION}).\n${versionList(newer)}`);
     }
-    if (outdated)
-        throw new ConfigurationError(OUTDATED);
-    if (newer.length > 0)
-        throw new ConfigurationError(newer.join(" "));
 }
 export async function runMigrate(workspace, options = {}) {
-    const adapters = options.adapters ?? migrationAdapters();
-    const rewrites = pendingRewrites(workspace, adapters);
+    const providers = options.providers ?? migrationProviders();
+    const rewrites = pendingRewrites(workspace, providers);
     if (rewrites.length === 0) {
         process.stdout.write("Schema is current.\n");
         return 0;
@@ -43,10 +45,10 @@ export async function runMigrate(workspace, options = {}) {
     process.stdout.write(`Upgraded schema to version ${SCHEMA_VERSION}.\n`);
     return 0;
 }
-export function migrationAdapters(adapters = adapterMap()) {
+export function migrationProviders(providers = providerMap()) {
     const mapped = {};
-    for (const [name, adapter] of Object.entries(adapters)) {
-        const candidate = adapter;
+    for (const [name, provider] of Object.entries(providers)) {
+        const candidate = provider;
         mapped[name] = {
             modelMigrations: candidate.modelMigrations ?? {},
             roleMigrations: candidate.roleMigrations ?? {},
@@ -74,17 +76,17 @@ async function accepted(confirm) {
     }
     return true;
 }
-function pendingRewrites(workspace, adapters) {
+function pendingRewrites(workspace, providers) {
     const configPath = path.join(workspace, ".migent", "config.yaml");
     if (!isFile(configPath))
         return [];
-    const [config, configRewrite] = configRewriteOf(configPath, adapters);
+    const [config, configRewrite] = configRewriteOf(configPath, providers);
     if (config === null)
         return [];
     const rewrites = [];
     if (configRewrite !== null)
         rewrites.push(configRewrite);
-    rewrites.push(...workflowRewrites(workspace, config, adapters));
+    rewrites.push(...workflowRewrites(workspace, config, providers));
     return rewrites;
 }
 function schemaFiles(workspace) {
@@ -109,7 +111,7 @@ function storedVersion(filePath) {
         return null;
     }
 }
-function configRewriteOf(filePath, adapters) {
+function configRewriteOf(filePath, providers) {
     const original = readFileSync(filePath, "utf8");
     let parsed;
     try {
@@ -121,7 +123,7 @@ function configRewriteOf(filePath, adapters) {
     const updated = structuredClone(parsed);
     let notes;
     try {
-        notes = migrateConfig(updated, adapters);
+        notes = migrateConfig(updated, providers);
     }
     catch (error) {
         if (error instanceof ConfigurationError)
@@ -136,7 +138,7 @@ function configRewriteOf(filePath, adapters) {
     const labeled = notes.map((note) => note.startsWith("schema_version") ? `Migrated .migent/config.yaml ${note}` : note);
     return [updated, { path: filePath, text: rewritten, notes: labeled }];
 }
-function workflowRewrites(workspace, config, adapters) {
+function workflowRewrites(workspace, config, providers) {
     const directory = workflowsDirectory(workspace);
     if (!isDirectory(directory))
         return [];
@@ -156,7 +158,7 @@ function workflowRewrites(workspace, config, adapters) {
         const updated = structuredClone(parsed);
         let changed;
         try {
-            changed = migrateWorkflow(updated, config, adapters);
+            changed = migrateWorkflow(updated, config, providers);
         }
         catch (error) {
             if (error instanceof ConfigurationError)

package/dist/program.js

@@ -11,6 +11,7 @@ import { runInit } from "./commands/init.js";
 import { runSessionMetrics, runSessions } from "./commands/sessions.js";
 import { parsePort, runServiceStart, runServiceStatus, runServiceStop } from "./commands/service.js";
 import { installSkill, updateSkill } from "./commands/skill.js";
+import { runProviderList } from "./commands/provider.js";
 import { runRegister, runRemove, runWorkspaceList } from "./commands/workspace-registry.js";
 import { printError } from "./display.js";
 import { LOOP_EXITS, STAGE_EXITS } from "./exits.js";
@@ -127,6 +128,18 @@ export function createProgram(status) {
         .option("--json", "Print the checks as one JSON object.")
         .addHelpText("after", exitText(["Exit 0 when every check passes.", "Exit 1 when a check fails."]))
         .action((options) => settle(status, () => runDoctor(findWorkspace(invocationCwdPath()), { asJson: options.json === true })));
+    const provider = program.command("provider").description("List registered provider providers and their models.");
+    provider
+        .command("list")
+        .description("List each registered provider, whether its CLI is on PATH, and the models it reports.")
+        .option("--json", "Print the provider list as one JSON object.")
+        .addHelpText("after", exitText([
+        "Exit 0 when the command ran and at least one provider returned models.",
+        "Exit 1 when no provider returned any models.",
+        "A missing optional CLI is not an error.",
+    ]))
+        .action((options) => settle(status, () => runProviderList({ asJson: options.json === true })));
+    showHelpWhenBare(status, provider);
     program
         .command("migrate")
         .description("Upgrade config and workflows to the current schema version.")
@@ -220,15 +233,15 @@ function registerSessionCommand(program, status) {
         .option("--file <file>", "Read the role prompt from this file.")
         .option("--stdin", "Read the role prompt from stdin.")
         .option("--json", "Print the role result as one JSON object.")
-        .addHelpText("after", `With --workflow:\n${exitText(LOOP_EXITS)}With --workflow and --once:\n${exitText(STAGE_EXITS)}Without --workflow:\n${exitText(ROLE_EXITS)}Examples:\n  migent session run --workflow plan --task "<one line>"\n  migent session run --session wave-3 --workflow plan\n  migent session run --role reviewer --prompt "<prompt>"\n`)
+        .addHelpText("after", `With --workflow:\n${exitText(LOOP_EXITS)}With --workflow and --once:\n${exitText(STAGE_EXITS)}Without --workflow:\n${exitText(ROLE_EXITS)}Examples:\n  migent session run --workflow plan --task "<one line>"\n  migent session run --session <session> --workflow plan\n  migent session run --role reviewer --prompt "<prompt>"\n`)
         .action((options) => settle(status, () => runSessionCommand(options)));
     session
         .command("prepare")
         .description("Create a prepared session and exit. Write task.md, then session run --session <id> --workflow <workflow>.")
-        .argument("<id>", "Session id: a lowercase slug such as wave-3.")
+        .argument("<title>", "Session title shown in the list, such as \"some task title\". The session id is a UUID.")
         .requiredOption("--workflow <workflow>", "Workflow id, or a path to a workflow file.")
         .option("--prior <session>", PRIOR_HELP)
-        .addHelpText("after", `${exitText(["Exit 0 when the session is prepared.", "Exit 2 on a configuration error."])}Examples:\n  migent session prepare wave-3 --workflow plan\n`)
+        .addHelpText("after", `${exitText(["Exit 0 when the session is prepared.", "Exit 2 on a configuration error."])}Examples:\n  migent session prepare "some task title" --workflow plan\n`)
         .action((id, options) => settle(status, () => prepareWorkflowSession(findWorkspace(invocationCwdPath()), id, String(options.workflow), optionalText(options.prior))));
     const continueCommand = session
         .command("continue")

package/dist/provider.d.ts

@@ -1,23 +1,25 @@
 import { ModelCatalog } from "@nodeint/migent-adapters";
-import { type AgentAdapter, type ProviderOption } from "@nodeint/migent-kernel";
-export interface CatalogAdapter extends AgentAdapter {
+import { type Provider, type ProviderOption } from "@nodeint/migent-kernel";
+export interface CatalogProvider extends Provider {
     modelCatalogCommand(): string[];
+    /** Written to the catalog command's stdin when the CLI reads its request there. */
+    modelCatalogInput?(): string;
     parseModelCatalog(stdout: string): ModelCatalog;
     optionValuesCommand(name: string, model: string): string[] | null;
     parseOptionValues(name: string, text: string, model?: string): readonly string[];
     providerOptions(): readonly ProviderOption[];
 }
 export type Which = (command: string) => string | null;
-export type RunCommand = (argv: string[]) => string | Promise<string>;
+export type RunCommand = (argv: string[], input?: string) => string | Promise<string>;
 export declare class ProviderCommandFailed extends Error {
 }
-export declare function adapterMap(): Record<string, AgentAdapter>;
-export declare function asCatalog(adapter: AgentAdapter): CatalogAdapter;
-export declare function requireAdapter(adapters: Record<string, AgentAdapter>, provider: string): AgentAdapter;
-export declare function detected(adapters: Record<string, AgentAdapter>, which: Which): Array<[string, string | null, AgentAdapter]>;
-export declare function loadCatalog(adapter: AgentAdapter, which: Which, runCommand: RunCommand): Promise<ModelCatalog>;
+export declare function providerMap(): Record<string, Provider>;
+export declare function asCatalog(provider: Provider): CatalogProvider;
+export declare function requireProvider(providers: Record<string, Provider>, provider: string): Provider;
+export declare function detected(providers: Record<string, Provider>, which: Which): Array<[string, string | null, Provider]>;
+export declare function loadCatalog(provider: Provider, which: Which, runCommand: RunCommand): Promise<ModelCatalog>;
 export declare function knownModel(model: string, catalog: ModelCatalog): string;
 export declare function parseOptions(pairs: readonly string[]): Record<string, string>;
-export declare function loadOptionValues(adapter: AgentAdapter, name: string, model: string, catalog: ModelCatalog, which: Which, runCommand: RunCommand): Promise<readonly string[] | null>;
-export declare function acceptedOptions(adapter: AgentAdapter, model: string, catalog: ModelCatalog, which: Which, runCommand: RunCommand, options: Readonly<Record<string, string>>): Promise<Record<string, string>>;
-export declare function runProviderCommand(argv: string[]): string;
+export declare function loadOptionValues(provider: Provider, name: string, model: string, catalog: ModelCatalog, which: Which, runCommand: RunCommand): Promise<readonly string[] | null>;
+export declare function acceptedOptions(provider: Provider, model: string, catalog: ModelCatalog, which: Which, runCommand: RunCommand, options: Readonly<Record<string, string>>): Promise<Record<string, string>>;
+export declare function runProviderCommand(argv: string[], input?: string): string;

package/dist/provider.js

@@ -1,27 +1,27 @@
-import { ModelCatalog, defaultAdapters } from "@nodeint/migent-adapters";
+import { ModelCatalog, defaultProviders } from "@nodeint/migent-adapters";
 import { spawnProviderSync } from "@nodeint/migent-kernel";
 export class ProviderCommandFailed extends Error {
 }
-export function adapterMap() {
-    return defaultAdapters();
+export function providerMap() {
+    return defaultProviders();
 }
-export function asCatalog(adapter) {
-    const candidate = adapter;
+export function asCatalog(provider) {
+    const candidate = provider;
     if (typeof candidate.modelCatalogCommand !== "function" || typeof candidate.parseModelCatalog !== "function") {
-        throw new ProviderCommandFailed(`${adapter.command} does not list models.`);
+        throw new ProviderCommandFailed(`${provider.command} does not list models.`);
     }
     return candidate;
 }
-export function requireAdapter(adapters, provider) {
-    const adapter = adapters[provider];
-    if (adapter === undefined) {
-        const supported = Object.keys(adapters).sort().join(", ");
+export function requireProvider(providers, provider) {
+    const impl = providers[provider];
+    if (impl === undefined) {
+        const supported = Object.keys(providers).sort().join(", ");
         throw new ProviderCommandFailed(`Unknown provider: ${provider}. Supported: ${supported}.`);
     }
-    return adapter;
+    return impl;
 }
-export function detected(adapters, which) {
-    const rows = Object.entries(adapters).map(([name, adapter]) => [name, which(adapter.command), adapter]);
+export function detected(providers, which) {
+    const rows = Object.entries(providers).filter(([, provider]) => provider.requiresClient !== true).map(([name, provider]) => [name, which(provider.command), provider]);
     rows.sort((left, right) => {
         const leftMissing = left[1] === null ? 1 : 0;
         const rightMissing = right[1] === null ? 1 : 0;
@@ -35,24 +35,24 @@ export function detected(adapters, which) {
     });
     return rows;
 }
-export async function loadCatalog(adapter, which, runCommand) {
-    if (which(adapter.command) === null) {
-        throw new ProviderCommandFailed(`${adapter.command} is not on PATH, so its models could not be listed.`);
+export async function loadCatalog(provider, which, runCommand) {
+    if (which(provider.command) === null) {
+        throw new ProviderCommandFailed(`${provider.command} is not on PATH, so its models could not be listed.`);
     }
-    const catalogAdapter = asCatalog(adapter);
+    const catalogProvider = asCatalog(provider);
     let stdout;
     try {
-        stdout = await runCommand(catalogAdapter.modelCatalogCommand());
+        stdout = await runCommand(catalogProvider.modelCatalogCommand(), catalogProvider.modelCatalogInput?.());
     }
     catch (error) {
         if (error instanceof ProviderCommandFailed)
             throw error;
         const reason = error instanceof Error ? error.message : String(error);
-        throw new ProviderCommandFailed(`Could not list ${adapter.command} models: ${reason}`);
+        throw new ProviderCommandFailed(`Could not list ${provider.command} models: ${reason}`);
     }
-    const catalog = catalogAdapter.parseModelCatalog(stdout);
+    const catalog = catalogProvider.parseModelCatalog(stdout);
     if (catalog.ids.length === 0)
-        throw new ProviderCommandFailed(`${adapter.command} returned no models.`);
+        throw new ProviderCommandFailed(`${provider.command} returned no models.`);
     return catalog;
 }
 export function knownModel(model, catalog) {
@@ -75,16 +75,16 @@ export function parseOptions(pairs) {
     }
     return parsed;
 }
-export async function loadOptionValues(adapter, name, model, catalog, which, runCommand) {
+export async function loadOptionValues(provider, name, model, catalog, which, runCommand) {
     const found = catalog.valuesFor(model, name);
     if (found !== null)
         return found;
-    const catalogAdapter = asCatalog(adapter);
-    const argv = catalogAdapter.optionValuesCommand(name, model);
+    const catalogProvider = asCatalog(provider);
+    const argv = catalogProvider.optionValuesCommand(name, model);
     if (argv === null)
         return null;
-    if (which(adapter.command) === null) {
-        throw new ProviderCommandFailed(`${adapter.command} is not on PATH, so its ${name} values could not be listed.`);
+    if (which(provider.command) === null) {
+        throw new ProviderCommandFailed(`${provider.command} is not on PATH, so its ${name} values could not be listed.`);
     }
     let text;
     try {
@@ -95,18 +95,18 @@ export async function loadOptionValues(adapter, name, model, catalog, which, run
             text = error.message;
         else {
             const reason = error instanceof Error ? error.message : String(error);
-            throw new ProviderCommandFailed(`Could not list ${adapter.command} ${name} values for ${model}: ${reason}`);
+            throw new ProviderCommandFailed(`Could not list ${provider.command} ${name} values for ${model}: ${reason}`);
         }
     }
-    return catalogAdapter.parseOptionValues(name, text, model);
+    return catalogProvider.parseOptionValues(name, text, model);
 }
-export async function acceptedOptions(adapter, model, catalog, which, runCommand, options) {
+export async function acceptedOptions(provider, model, catalog, which, runCommand, options) {
     if (Object.keys(options).length === 0)
         return {};
-    adapter.validateOptions(options);
+    provider.validateOptions(options);
     const stored = {};
     for (const [name, value] of Object.entries(options)) {
-        const values = await loadOptionValues(adapter, name, model, catalog, which, runCommand);
+        const values = await loadOptionValues(provider, name, model, catalog, which, runCommand);
         if (values === null) {
             stored[name] = value;
             continue;
@@ -120,11 +120,16 @@ export async function acceptedOptions(adapter, model, catalog, which, runCommand
     }
     return stored;
 }
-export function runProviderCommand(argv) {
+export function runProviderCommand(argv, input) {
     const [command, ...args] = argv;
     if (command === undefined)
         throw new ProviderCommandFailed("Provider command is empty.");
-    const completed = spawnProviderSync(command, args, { encoding: "utf8", timeout: 60_000, windowsHide: true });
+    const completed = spawnProviderSync(command, args, {
+        encoding: "utf8",
+        timeout: 60_000,
+        windowsHide: true,
+        ...(input === undefined ? {} : { input }),
+    });
     if (completed.error) {
         throw new Error(completed.error.message);
     }

package/dist/session-row.d.ts

@@ -7,9 +7,11 @@ export declare const SESSION_COLUMN: {
     readonly decision: 5;
     readonly outputs: 6;
     readonly task: 7;
+    readonly title: 8;
 };
 export interface SessionFields {
     session: string;
+    title: string;
     workflow: string;
     status: string;
     execution: string;

package/dist/session-row.js

@@ -7,10 +7,12 @@ export const SESSION_COLUMN = {
     decision: 5,
     outputs: 6,
     task: 7,
+    title: 8,
 };
 export function sessionFields(row) {
     return {
         session: row[SESSION_COLUMN.session] ?? "",
+        title: row[SESSION_COLUMN.title] ?? "",
         workflow: row[SESSION_COLUMN.workflow] ?? "",
         status: row[SESSION_COLUMN.status] ?? "",
         execution: row[SESSION_COLUMN.execution] ?? "",

package/dist/templates/migent/SKILL.md

@@ -21,6 +21,9 @@ This skill is already in the prompt. Do not open its file again.
   and `schema-workflow.yaml` in the same folder. A key absent from them is
   ignored. Then run `migent doctor --json`; if it reports an outdated schema,
   run `migent migrate --yes`.
+- `.migent/config.local.yaml`, when present, overrides `config.yaml` on this
+  machine. It is not committed. Read both, and edit shared settings in
+  `config.yaml`, not the local file.
 - You have no terminal for prompts. Pass `--no-input` (or set
   `MIGENT_NO_INPUT=1`) to `init`, `config model`, and `config role`, and give
   every value as a flag.
@@ -41,18 +44,18 @@ One-line task. The command runs until the session stops:
 migent session run --workflow <workflow> --task "<task>"
 ```
 
-Longer task. `<some-id>` is a lowercase slug such as `wave-3`:
+Longer task. `<title>` is a display label such as `some task title`. The command prints a UUID `session_id`:
 
 ```
-migent session prepare <some-id> --workflow <workflow>
+migent session prepare "<title>" --workflow <workflow>
 ```
 
-Write the task, unchanged, to `.migent/sessions/<some-id>/task.md` (plus any
-files next to it). Do not edit `task.md` once the first stage has started.
+Write the task, unchanged, to the printed `task_path` (plus any files next to it).
+Do not edit `task.md` once the first stage has started.
 Then:
 
 ```
-migent session run --session <some-id> --workflow <workflow>
+migent session run --session <session-id> --workflow <workflow>
 ```
 
 Dispatch only one stage: add `--once`.
@@ -122,18 +125,22 @@ migent session list --latest --json
 ```
 
 `show` gives status, latest execution, decision, and outputs. `list --latest`
-is the newest session, or `null`. Report the session ID, status, stop reason,
+is the newest session, or `null`. Both include `title` when the session has one.
+Report the session ID, title, status, stop reason,
 decisions, and the outputs that matter. Output paths are relative to
 `.migent/sessions/<session-id>/`; use the paths Migent reports.
 
 ## Set up a project
 
 ```
+migent provider list --json
 migent init --no-input --provider <provider> --model <model-id> [--preset implement|plan] [--skill]
 migent doctor --json
 ```
 
 `--provider` and `--model` go together. The default preset is `implement`.
+`provider list --json` shows which provider CLIs are on PATH and what model
+ids each supports. Use it to pick a `<provider>` and `<model-id>` for `init`.
 `--skill` installs this skill; `migent skill update` refreshes it.
 
 ## Change models

package/dist/templates/migent/references/config.md

@@ -2,6 +2,19 @@
 
 Write commands take `--no-input --json`. The JSON includes the doctor result.
 
+Run `migent provider list --json` to see which provider CLIs are available
+and what model ids each supports. Use that output to pick a provider and
+model id before using `config model` or `init`.
+
+## Per-machine override
+
+`.migent/config.local.yaml` is an optional, uncommitted file with the same keys
+as `config.yaml`. Mappings merge key by key; scalars and lists, such as
+`instructions`, replace the value from `config.yaml`. Its `schema_version` is
+ignored. Runs, `doctor`, and `config show` read the merged result.
+`config model` and `config role` edit `config.yaml` only, never the local file.
+`doctor` warns if git tracks the local file.
+
 ## Run one role
 
 Without `--workflow`, `session run` runs a single role:

package/dist/templates/migent/references/schema-config.yaml

@@ -1,10 +1,15 @@
 # A missing schema_version is 0. Commands refuse the file while it is older than this Migent.
 schema_version: 2
+# .migent/config.local.yaml is an optional per-machine override with the same keys. It is not committed.
+# Mappings merge key by key; scalars and lists replace the value from config.yaml. Its schema_version is ignored.
+# config model and config role edit config.yaml only.
 
 # models.<name>.model is the provider model id.
+# models.<name>.client is optional: the CLI client id (agy, claude-code, codex, grok, opencode); required for provider byteplus
+# that drives this model. Omit it to use the provider's own client.
 # roles.<name>.default_model and a stage model are this name.
 # Options merge in order: model, then role, then stage.
-# Only keys the adapter marks overridable are stored on the provider session.
+# Only keys the provider marks overridable are stored on the provider session.
 models:
   planner:
     provider: grok
@@ -19,9 +24,16 @@ models:
     # disallowed_tools, max_budget_usd, fallback_model, and append_system_prompt.
     # codex accepts model_reasoning_effort (overridable). Any other key of letters, digits,
     # dots, underscores, and hyphens is passed through as codex exec -c.
+    # opencode accepts agent and thinking (true sends --thinking, false sends nothing). Neither is overridable.
     options:
       reasoning-effort: high
 
+  coder:
+    provider: byteplus
+    # byteplus has no CLI of its own, so client is required and names the CLI that runs it.
+    client: opencode
+    model: coding-plan/deepseek-v4-pro
+
 roles:
   planner:
     default_model: planner

package/dist/templates/migent/references/schema-workflow.yaml

@@ -27,7 +27,7 @@ stages:
     # model is a name under models in config.yaml, not a provider model id.
     model: planner
     # Options merge in order: model, then role, then stage.
-    # Only keys the adapter marks overridable are stored on the provider session.
+    # Only keys the provider marks overridable are stored on the provider session.
     options:
       reasoning-effort: high
     depends_on:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodeint/migent",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Compose AI coding agents into repeatable engineering workflows.",
   "keywords": [
     "ai",
@@ -43,9 +43,9 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.8.1",
-    "@nodeint/migent-adapters": "0.1.6",
-    "@nodeint/migent-kernel": "0.1.6",
-    "@nodeint/migent-registry": "0.1.6",
+    "@nodeint/migent-adapters": "0.1.8",
+    "@nodeint/migent-kernel": "0.1.8",
+    "@nodeint/migent-registry": "0.1.8",
     "commander": "^14.0.2",
     "picocolors": "^1.1.1"
   },