@nodeint/migent 0.1.7 → 0.1.8

package/README.md

@@ -1,253 +1,341 @@
 # Migent
 
 <p align="center">
-  <img src="assets/stylized-m.svg" alt="Migent logo" width="150" /><br>
-  <strong>Autonomous, multi-stage engineering pipelines for your coding agents.</strong><br>
-  Repeatable workflows. Multi-agent orchestration. Native CLI execution. Full observability.
+  <img src="https://raw.githubusercontent.com/nodeint/migent/main/assets/stylized-m.svg" alt="Migent logo" width="150" /><br>
+  <strong>Compose AI coding agents into repeatable engineering workflows.
+</strong>
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@nodeint/migent"><img src="https://img.shields.io/npm/v/@nodeint/migent.svg?style=flat-square" alt="npm version" /></a>
   <a href="https://github.com/nodeint/migent/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="License: MIT" /></a>
   <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen.svg?style=flat-square" alt="Node.js 22+" /></a>
-  <img src="https://img.shields.io/badge/agents-Multi--Agent_Ready-orange.svg?style=flat-square" alt="Multi-Agent Ready" />
 </p>
 
 ---
 
-Migent coordinates the coding-agent CLIs you already have into **reusable, verified engineering pipelines**. Instead of juggling tabs, manually copying plans, and pasting test errors back and forth, you define the pipeline as code. Migent orchestrates the handoffs, runs strict local verification gates, handles review loops, and captures deep execution metrics.
 
-### 🌟 Why Migent?
+Migent connects coding-agent CLIs from different providers through explicit,
+repository-defined workflows. One model can plan, another can review, and the
+first can revise—while Migent carries artifacts between them and remembers
+where the process is.
+
+## Contents
+
+- [Migent](#migent)
+  - [Contents](#contents)
+  - [Why Migent?](#why-migent)
+  - [Supported CLIs](#supported-clis)
+  - [Quickstart](#quickstart)
+    - [Install](#install)
+    - [Install agent skill](#install-agent-skill)
+    - [Create a project](#create-a-project)
+      - [Option 1: Ask your AI agent](#option-1-ask-your-ai-agent)
+      - [Option 2: Run `migent init`](#option-2-run-migent-init)
+    - [Run](#run)
+  - [Workflow as code](#workflow-as-code)
+    - [How decisions work](#how-decisions-work)
+    - [Beyond planning: code and verify](#beyond-planning-code-and-verify)
+  - [Concepts](#concepts)
+    - [Artifact handoff vs session resume](#artifact-handoff-vs-session-resume)
+    - [Built-in safeguards](#built-in-safeguards)
+  - [Current scope](#current-scope)
+  - [Documentation](#documentation)
+  - [Development](#development)
+  - [License](#license)
+
+## Why Migent?
+
+Calling two agent CLIs from a shell script is easy. Reliably coordinating them
+across reviews, revisions, failures, and resumed sessions is not.
+
+Migent is built around three ideas:
+
+- **Use models for what they do best.** Assign each role to a provider and model
+  suited to the work, rather than asking one agent to do everything.
+- **Treat AI engineering process as code.** Keep stages, handoffs, review gates,
+  and revision policies in version control beside the project they govern.
+- **Keep orchestration explicit.** The team defines the process; models execute
+  roles inside it. A supervisor model does not invent or dynamically control
+  the workflow.
+
+**Models describe execution. Roles describe intent.** Changing the model behind
+a role does not require rewriting the workflow.
+
+**Common workflow model, native provider capabilities.** Migent coordinates
+the process, while each provider CLI remains responsible for authentication,
+agent execution, and its own tools and options.
 
-- 🔁 **Automate Recurring Tasks (Workflows & Stages):** Package routine engineering work—bug fixes, refactors, migrations, test authoring—into structured, multi-stage pipelines with deterministic verification gates.
-- 🤖 **Multi-Agent Orchestration & Flexibility:** Assign the best model to each role (`claude` for planning, `codex` for implementation, `grok` for independent review). Run directly through your installed agent CLIs without custom wrappers or API lock-in.
-- 📊 **Observability & Continuous Improvement:** Live-stream running pipelines with `session follow`, and collect token spend, wall-time, and revision counts with `session metrics` to measure and refine your team's workflows.
+```mermaid
+flowchart TD
+    A[Task] --> B[Planner - Codex]
+    B -->|plan.md| C[Reviewer - Grok]
+    C -->|revise| B
+    C -->|approved| D[Complete]
+```
 
----
+## Supported CLIs
+
+Migent drives each provider through its headless CLI. Install and sign in to the
+ones your configuration names.
+
+| Provider           | CLI          |
+| -------------------| -------------|
+| Google Antigravity | `agy`        |
+| Claude             | `claude`     |
+| Codex              | `codex`      |
+| Grok               | `grok`       |
+| BytePlus           | `opencode`   |
+| OpenCode           | `opencode`   |
 
 ## Quickstart
 
-### Option A: Agent-Assisted via `/migent` (Recommended)
+Requires Node.js 22+ (macOS, Linux, or Windows) and the provider CLIs your
+config uses, already signed in.
 
-Let your coding agent handle the initial configuration using Migent's official Skill.
+### Install
 
 ```bash
-# 1. Install Migent globally
 npm install -g @nodeint/migent
-
-# 2. Install the Migent Skill in your repo
-migent skill install
+migent --version
 ```
 
-Now open your favorite coding agent CLI (such as Google Antigravity `agy`, Anthropic `claude`, Cursor, or Windsurf) in this repository and type:
+Upgrade with `npm install -g @nodeint/migent@latest`.
 
-```text
-/migent Set up a workflow for this repo: Claude for planning, Codex for coding, Grok for review. Then run a pipeline to resolve issue #42.
+### Install agent skill
+
+From your project repository:
+
+```bash
+migent skill install
 ```
 
-> **How it works:** `migent skill install` creates `.agents/skills/migent/` containing Migent's schema rules and CLI definitions. Using the `/migent` slash command instructs your agent to inspect your repo, generate valid configuration files under `.migent/`, validate them with `migent doctor`, and launch the workflow.
+Installs `.agents/skills/migent/` so your AI agent knows how to configure, run,
+and inspect Migent workflows.
 
----
+### Create a project
 
-### Option B: Terminal CLI (Direct Control)
+Choose one:
 
-Prefer setting it up yourself? Get started in three commands:
+#### Option 1: Ask your AI agent
 
-```bash
-# 1. Initialize a workflow preset and validate environment
-migent init --preset plan
-migent doctor
+Paste this prompt into your agent (Claude Code, Antigravity, Cursor, etc.):
 
-# 2. Run your engineering task
-migent session run --workflow plan --task "Implement JWT authentication with refresh tokens"
+```text
+Load skill migent: Read and follow .agents/skills/migent/SKILL.md.
 
-# 3. Stream real-time events or inspect performance metrics
-migent session follow <session-id>
-migent session metrics <session-id> --json
+Instructions: Initialize Migent for this project using the installed provider CLIs, set up .migent/config.yaml and .migent/workflows/plan.yaml, and run `migent doctor` to verify.
 ```
 
----
+#### Option 2: Run `migent init`
 
-## What Migent Solves
+```bash
+migent init
+```
 
-| Without Migent | With Migent |
-| :--- | :--- |
-| **Manual handoffs:** Copying plans and pasting stack traces across conversations. | **Automated handoffs:** Upstream artifacts and diffs pass automatically into downstream stages. |
-| **Single-agent bottleneck:** One model handles planning, coding, and review, accumulating context bloat. | **Specialized roles:** Multi-agent pipeline with dedicated models per role (e.g., Planner $\rightarrow$ Coder $\rightarrow$ Reviewer). |
-| **Vendor lock-in & wrappers:** Restricted to one provider or requiring custom API providers. | **Native CLI execution:** Drives your installed agent CLIs (`agy`, `claude`, `codex`, `grok`) directly in your workspace. |
-| **Blind trust:** Agents claim "all tests pass" without actually running project commands. | **Verification gates:** Real local checks (`pnpm test`, `pytest`, `cargo test`) must succeed before advancing. |
-| **Fragile one-off prompts:** Team members execute tasks with inconsistent, ad-hoc instructions. | **Process as code:** Workflows live in Git (`.migent/workflows/`), making best practices versioned and repeatable. |
-| **No execution visibility:** No record of how long tasks took, why checks failed, or how many retries occurred. | **Telemetry & Metrics:** Append-only event logs, live streaming, and full JSON metrics for duration, retries, and token cost. |
+Follow the interactive prompts to select providers and models.
 
----
+Both options generate:
 
-## How It Works
+```text
+.migent/
+├── config.yaml        # models and roles
+├── config.local.yaml  # optional per-machine override, not committed
+├── .gitignore         # keeps sessions/ untracked
+└── workflows/
+    └── plan.yaml      # plan-and-review workflow
+```
 
-A typical software engineering workflow breaks down into structured, verifiable stages:
+Commit `config.yaml` and `workflows/`. `config.local.yaml` overrides `config.yaml` on one machine and is ignored by git.
 
-```mermaid
-flowchart TD
-    Task["Task: Fix OAuth Callback"] --> Plan["1. Plan\n(Claude)"]
-    Plan -->|"artifact: plan.md"| Implement["2. Implement\n(Codex)"]
-    Implement --> Verify{"3. Verification Gate\n(pnpm test)"}
-    Verify -->|"Fails (retry <= max)"| Implement
-    Verify -->|"Retry limit reached"| Blocked["Stop for inspection"]
-    Verify -->|"Passes"| Review["4. Review\n(Grok)"]
-    Review -->|"Revise + feedback"| Implement
-    Review -->|"Approved"| Done["Workflow Complete"]
-```
+### Run
 
-1. **Plan:** A high-reasoning model analyzes the codebase and generates an actionable `plan.md`.
-2. **Implement:** A coding model applies changes to the working tree according to the plan.
-3. **Verify Gate:** Migent runs your repository's native verification commands (tests, typecheck, lint).
-4. **Review & Revision Loop:** An independent reviewer evaluates the git diff against the plan. If changes are requested, feedback routes back to the implementation stage.
+Start a workflow from your project directory:
 
----
+```bash
+$ migent session run --workflow plan --task "Plan the account settings redesign"
 
-## Core Capabilities
+stage plan · attempt 1 · 10:15:30 · codex/gpt-5 · complete.
+stage review-plan · attempt 1 · 10:16:15 · grok/grok-4 · complete decision=revise.
+stage plan · attempt 2 · 10:17:00 · codex/gpt-5 · complete.
+stage review-plan · attempt 2 · 10:17:45 · grok/grok-4 · complete decision=approved.
 
-### 1. Repeatable Workflows as Code
-Define stages, dependencies, artifacts, and routing decisions in declarative YAML stored under `.migent/workflows/`. Version control your engineering processes alongside your application code.
+Session completed in 2m 15s.
+.migent/sessions/20261022-101530--wave-1/outputs/plan.md
+```
 
-### 2. Multi-Agent Orchestration & BYO CLIs
-Decouple **what** a stage does from **which model** executes it. Migent drives the agent CLIs already installed and authenticated on your machine:
+Inspect sessions or resume a stopped run:
 
-| Provider | CLI | Typical Role in Pipeline |
-| :--- | :--- | :--- |
-| **Anthropic Claude** | `claude` | High-reasoning architecture planning & refactoring |
-| **Google Antigravity** | `agy` | Deep repository analysis, plan generation & review |
-| **OpenAI Codex** | `codex` | Fast, focused implementation & unit test authoring |
-| **xAI Grok** | `grok` | Independent logic review & edge case discovery |
-| **OpenCode** | `opencode` | Multi-vendor models behind one CLI, for any role |
-| **BytePlus ModelArk** | none (set `client` per model) | BytePlus models run through another installed CLI, e.g. `opencode` |
+```bash
+migent session list
+migent session continue <session-id>
+```
 
-Switch models anytime in `.migent/config.yaml` without touching your workflow logic.
+## Workflow as code
 
-### 3. Observability, Telemetry & Continuous Improvement
-Migent treats engineering runs as first-class observable processes:
-- **Live Monitoring:** `migent session follow <session-id>` streams execution events, stage heartbeats, and runner turns in real time.
-- **Detailed Metrics:** `migent session metrics <session-id> --json` outputs execution wall-time, active runner seconds, verify durations, revision counts, and token usage.
-- **Continuous Refinement:** Use hard metrics from past sessions to optimize prompts, tune retry limits, and pick the most cost-effective models.
-- **Session Recovery:** When rate limits or network issues strike, `migent session continue <session-id>` resumes right where the pipeline stopped.
+Workflows live in `.migent/workflows/` and models in `.migent/config.yaml`.
 
----
+A standard plan-and-review workflow:
 
-## Configuration Example
+```yaml
+# .migent/workflows/plan.yaml
+schema_version: 2
+stages:
+  - id: plan
+    role: planner
+    max_revisions: 3
+    instructions:
+      - Read task.md and write plan.md into artifacts.
+    produces:
+      artifact: plan.md
 
-Migent separates model/role assignments from pipeline control flow.
+  - id: review-plan
+    role: reviewer
+    depends_on: [plan]
+    instructions:
+      - Verify plan.md against the codebase.
+      - Approve only if implementation can proceed without ambiguity.
+    decision:
+      values: [approved, revise]
+      routes:
+        approved: complete
+        revise: plan
+```
 
-### 1. Configure Models and Roles (`.migent/config.yaml`)
+And the roles backed by your chosen provider CLIs:
 
 ```yaml
+# .migent/config.yaml
 schema_version: 2
-
 models:
-  planning-model:
-    provider: claude
-    model: opus
-
-  coding-model:
+  codex-model:
     provider: codex
-    model: default
-
-  review-model:
+    model: gpt-5
+  grok-model:
     provider: grok
-    model: grok-4.7
+    model: grok-4
+    options:
+      reasoning-effort: high
 
 roles:
   planner:
-    default_model: planning-model
-    instructions:
-      - Analyze the repository and create an actionable plan with file paths.
+    default_model: codex-model
+  reviewer:
+    default_model: grok-model
+```
 
-  coder:
-    default_model: coding-model
-    instructions:
-      - Implement changes according to the plan and write regression tests.
+### How decisions work
 
-  reviewer:
-    default_model: review-model
-    instructions:
-      - Review the git diff against the plan for correctness, security, and edge cases.
+Migent enforces a clean, lightweight protocol. Stages communicate outcomes
+through standard RFC-style response headers injected into the prompt:
+
+```text
+status: complete
+decision: approved
+
+The implementation plan covers all requirements and test cases.
 ```
 
-### 2. Define the Pipeline (`.migent/workflows/feature.yaml`)
+When a stage completes, Migent routes execution based on the `decision` header.
+Review prose remains human-readable feedback passed directly to the next stage.
 
-```yaml
-schema_version: 2
-id: feature
+### Beyond planning: code and verify
 
-stages:
-  - id: plan
-    role: planner
-    produces:
-      artifact: plan.md
+Stages are not limited to generating documents. A stage can modify repository files
+and declare automated `verify` commands:
 
+```yaml
+stages:
   - id: implement
-    role: coder
-    depends_on: [plan]
+    role: developer
+    instructions:
+      - Implement the approved plan.
     verify:
+      - pnpm build
       - pnpm test
     max_verify: 3
+```
 
-  - id: review
-    role: reviewer
-    depends_on: [implement]
-    decision:
-      values: [approved, revise]
-      routes:
-        approved: complete
-        revise: implement
+Migent runs the verification commands in the workspace POSIX shell. If tests fail,
+Migent returns the command tail to the agent for an automated repair loop (up to
+`max_verify` attempts) before handing off to review.
 
-outputs:
-  - name: plan
-    from_stage: plan
-    artifact: plan.md
-```
+## Concepts
 
----
+A workflow connects stages through dependencies and explicit decision routes.
 
-## CLI Cheatsheet
+- A **model** identifies a provider model and its execution options.
+- A **role** names a kind of work and selects its default model.
+- A **stage** assigns work to a role and may declare dependencies, an artifact,
+  a decision, or verification commands.
+- An **artifact** is a named file produced by a successful stage and stored with
+  the workflow session.
+- A **decision** selects the next route, including a route back for revision.
+- A **session** records executions, events, decisions, and artifacts so work can
+  be inspected or resumed.
 
-```bash
-# Setup & Health
-migent init --preset plan           # Initialize starter configuration
-migent doctor                      # Validate configuration, schemas, and CLI availability
-migent provider list               # List registered provider providers and their available models
-migent skill install               # Install the Migent Skill for coding agents (.agents/skills/migent/)
-
-# Execution
-migent session run --workflow <id> --task "<task>"   # Run a workflow
-migent session continue <session-id>                 # Resume an interrupted or blocked session
-
-# Monitoring & Telemetry
-migent session list                                  # List recorded sessions and statuses
-migent session follow <session-id>                   # Live-stream session events and progress
-migent session metrics <session-id> --json           # View token spend, duration, and retry metrics
-migent session show <session-id>                     # Inspect session state and artifact status
-```
+### Artifact handoff vs session resume
 
----
+- `depends_on: [stage]`: Makes the upstream stage's artifacts available to the
+  current stage while starting a fresh provider agent. Best for clean context
+  handoffs between different roles and models.
+- `session.resume_from: <stage>`: Continues the upstream stage's provider conversation
+  thread. Best when an agent needs to keep its conversation memory and tool history.
+
+### Built-in safeguards
+
+Engineering workflows have explicit cost and execution guardrails:
+
+- **Revision limits (`max_revisions`)**: Prevents infinite critique loops between
+  agents.
+- **Dispatch circuit breaker (`--max-dispatches`)**: Halts execution if a run
+  exceeds the configured dispatch limit (default 20).
+- **Verification bounds (`max_verify`, `verify_timeout`)**: Limits automated
+  test/repair attempts.
+- **Session metrics (`metrics.json`)**: Tracks tokens, turns, and cost per execution
+  and session.
+
+## Current scope
+
+Migent is a local, file-backed orchestration layer for provider CLIs. It does
+not replace their agent runtimes, and it does not hide their distinctive
+capabilities behind a lowest-common-denominator API.
+
+Today, Migent supports explicit stage routing, review loops, local session
+history, provider-session resume, prerequisite workflows, and standalone role
+execution. A machine-local registry service records workspaces
+so another tool can ask which projects exist.
+
+Workflows can be run directly from the command line, or driven autonomously by your
+coding agent when the project has the Migent skill installed.
 
 ## Documentation
 
-- [Writing Workflows](https://github.com/nodeint/migent/blob/main/docs/workflows.md) — Stages, dependencies, artifacts, and routing decisions.
-- [Providers and Model Configuration](https://github.com/nodeint/migent/blob/main/docs/providers.md) — Configuring CLIs, models, options, and fallback models.
-- [Sessions and State](https://github.com/nodeint/migent/blob/main/docs/sessions.md) — Manifests, append-only event logs, and recovery.
-- [CLI Reference](https://github.com/nodeint/migent/blob/main/docs/cli.md) — Full command catalog, flags, and JSON modes.
+- [Writing workflows](https://github.com/nodeint/migent/blob/main/docs/workflows.md)
+- [Providers and model configuration](https://github.com/nodeint/migent/blob/main/docs/providers.md)
+- [Sessions and workflow composition](https://github.com/nodeint/migent/blob/main/docs/sessions.md)
+- [CLI commands and execution controls](https://github.com/nodeint/migent/blob/main/docs/cli.md)
+
+Run `migent <command> --help` for the exact command contract, output fields,
+and exit codes.
 
-## Contributing
+## Development
 
-Migent is built with TypeScript in a pnpm workspace:
+The pnpm workspace contains four packages: the `@nodeint/migent` CLI and its
+internal libraries `@nodeint/migent-kernel`, `@nodeint/migent-adapters`, and
+`@nodeint/migent-registry`. The libraries have no stable API; depend on
+`@nodeint/migent`.
 
 ```bash
 pnpm install
 pnpm build
 pnpm test
+pnpm migent --help   # run the local build
 ```
 
-See [CONTRIBUTING.md](https://github.com/nodeint/migent/blob/main/CONTRIBUTING.md) for details.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for testing rules, platform notes, and
+the release process.
 
 ## License
 
-Migent is open source under the [MIT License](https://github.com/nodeint/migent/blob/main/LICENSE).
+Migent is licensed under the [MIT License](https://github.com/nodeint/migent/blob/main/LICENSE).

package/dist/commands/agent.js

@@ -1,6 +1,6 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
-import { AgentToolRunner, CancellationRequested, ConfigurationError, ProviderEventReporter, SessionStore, createAgentSession, loadRoleInstructions, loadYamlMapping, log, prependRoleInstructions, requireAgentSession, isSessionLockLost, repairSessionUnlocked, SessionLock, stringOptions, resolveRoleTarget, waitUntil, } from "@nodeint/migent-kernel";
+import { AgentToolRunner, CancellationRequested, ConfigurationError, ProviderEventReporter, SessionStore, createAgentSession, loadRoleInstructions, loadYamlMapping, log, prependRoleInstructions, requireAgentSession, isSessionLockLost, repairSessionUnlocked, SessionLock, stringOptions, loadWorkspaceConfig, resolveRoleTarget, waitUntil, } from "@nodeint/migent-kernel";
 import { printAgent, printError, printNotice, printResumeCommand } from "../display.js";
 import { cliHooks } from "../hooks.js";
 import { requireCurrentSchema } from "../migrate.js";
@@ -100,7 +100,7 @@ export async function dispatchAgent(workspace, args) {
                     resumedMany = finished;
             }
             else {
-                const prompt = prependRoleInstructions(loadRoleInstructions(loadYamlMapping(path.join(workspace, ".migent", "config.yaml")), args.role), resolvePrompt({
+                const prompt = prependRoleInstructions(loadRoleInstructions(loadWorkspaceConfig(workspace), args.role), resolvePrompt({
                     prompt: args.prompt ?? null,
                     promptFile: args.promptFile ?? null,
                     promptStdin: args.promptStdin ?? false,
@@ -385,7 +385,7 @@ function finishRole(sessionId, code) {
     return code;
 }
 function rolePrompt(workspace, role, text) {
-    return prependRoleInstructions(loadRoleInstructions(loadYamlMapping(path.join(workspace, ".migent", "config.yaml")), role), text);
+    return prependRoleInstructions(loadRoleInstructions(loadWorkspaceConfig(workspace), role), text);
 }
 function executionProfile(directory, executionId) {
     const raw = JSON.parse(readFileSync(path.join(directory, "execution.json"), "utf8"));

package/dist/commands/config.js

@@ -1,7 +1,7 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { confirm as clackConfirm, isCancel, select as clackSelect, text as clackText } from "@clack/prompts";
-import { ConfigEditError, ConfigurationError, assignRoles, describeChange, diagnose, inspectConfig, loadModelTarget, loadWorkflowCatalog, loadYamlMapping, matchingModelName, patchConfigText, placeRoleModel, isRoleStage, resolveStageSpec, setRoleOptions, upsertModel, whichSync, } from "@nodeint/migent-kernel";
+import { ConfigEditError, ConfigurationError, LOCAL_CONFIG_FILE, assignRoles, configPath, describeChange, diagnose, hasLocalConfig, inspectConfig, loadModelTarget, loadWorkflowCatalog, loadWorkspaceConfig, loadYamlMapping, matchingModelName, patchConfigText, placeRoleModel, isRoleStage, resolveStageSpec, setRoleOptions, stringifyConfig, upsertModel, whichSync, } from "@nodeint/migent-kernel";
 import { printError } from "../display.js";
 import { PromptCancelled } from "../errors.js";
 import { cliHooks } from "../hooks.js";
@@ -11,8 +11,13 @@ import { runDoctor } from "./doctor.js";
 const NEW = "__new__";
 const UNSET = Symbol("unset");
 export function runConfigShow(workspace) {
-    const text = readFileSync(path.join(workspace, ".migent", "config.yaml"), "utf8");
-    process.stdout.write(text);
+    if (!hasLocalConfig(workspace)) {
+        process.stdout.write(readFileSync(configPath(workspace), "utf8"));
+        return 0;
+    }
+    process.stdout.write(stringifyConfig(loadWorkspaceConfig(workspace)));
+    process.stderr.write(`Merged with .migent/${LOCAL_CONFIG_FILE}.
+`);
     return 0;
 }
 export async function runConfigModel(workspace, options = {}) {
@@ -262,7 +267,8 @@ async function confirmAndCommit(workspace, change, prompter, asJson, which) {
     return commit(workspace, change, { asJson, which, echo: false });
 }
 async function commit(workspace, change, args) {
-    const filePath = path.join(workspace, ".migent", "config.yaml");
+    // Edits patch config.yaml only, so config.local.yaml values never reach the committed file.
+    const filePath = configPath(workspace);
     const original = readFileSync(filePath, "utf8");
     const updated = patchConfigText(original, change.config);
     if (updated === original) {
@@ -395,7 +401,8 @@ async function selectProvider(prompter, providers, which, message, defaultValue)
 }
 function loaded(workspace) {
     requireCurrentSchema(workspace);
-    const config = loadYamlMapping(path.join(workspace, ".migent", "config.yaml"));
+    // Base file only: this snapshot feeds validation and patching of config.yaml.
+    const config = loadYamlMapping(configPath(workspace));
     const workflows = Object.values(loadWorkflowCatalog(workspace).documents);
     return [config, workflows, inspectConfig(config, workflows)];
 }

package/dist/commands/doctor.js

@@ -21,6 +21,7 @@ function payload(checks) {
             ok: check.ok,
             items: [...check.items],
             problems: [...check.problems],
+            warnings: [...check.warnings],
         })),
     };
 }

package/dist/commands/init.js

@@ -168,7 +168,7 @@ function writeProject(workspace, preset, primary) {
     writeFileSync(path.join(root, "config.yaml"), renderConfig(preset, primary), "utf8");
     const workflowName = `${preset}.yaml`;
     writeFileSync(path.join(workflows, workflowName), renderWorkflow(preset), "utf8");
-    writeFileSync(path.join(root, ".gitignore"), "sessions/\n", "utf8");
+    writeFileSync(path.join(root, ".gitignore"), "sessions/\nconfig.local.yaml\n", "utf8");
     return [".migent/config.yaml", `.migent/workflows/${workflowName}`, ".migent/.gitignore"];
 }
 function renderConfig(preset, primary) {

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) {

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.

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

@@ -6,6 +6,15 @@ 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,5 +1,8 @@
 # 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodeint/migent",
-  "version": "0.1.7",
+  "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.7",
-    "@nodeint/migent-kernel": "0.1.7",
-    "@nodeint/migent-registry": "0.1.7",
+    "@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"
   },