@nodeint/migent 0.1.5 → 0.1.6

package/dist/program.js

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import { Command } from "commander";
-import { ConfigurationError, DEFAULT_MAX_DISPATCHES } from "@nodeint/migent-kernel";
-import { dispatchAgent } from "./commands/agent.js";
+import { ConfigurationError, DEFAULT_MAX_DISPATCHES, requireAgentSession } from "@nodeint/migent-kernel";
+import { continueAgent, dispatchAgent } from "./commands/agent.js";
 import { runConfigModel, runConfigRole, runConfigShow } from "./commands/config.js";
 import { runDoctor } from "./commands/doctor.js";
 import { executeWorkflow } from "./commands/execute.js";
@@ -20,7 +20,7 @@ import { PACKAGE_VERSION } from "./version.js";
 import { findWorkspace, invocationCwdPath } from "./workspace.js";
 const PRIOR_HELP = "Completed session with the workflow id and decision named in requires. Checked before outputs are injected.";
 const PROGRESS_HELP = "Print each tool call when it finishes. The default prints one line when a stage starts and one when it finishes.";
-const VERBOSE_HELP = "Include every stage and its response text in the result JSON.";
+const VERBOSE_HELP = "Accepted for compatibility. Stage lines already include the attempt and the time. The response stays in the execution directory.";
 export function createProgram(status) {
     const program = new Command();
     program
@@ -195,10 +195,11 @@ export function createProgram(status) {
     return program;
 }
 const ROLE_EXITS = [
-    "Exit 0 when the outcome is complete.",
+    "Exit 0 when the outcome is complete, or the role session is already completed.",
     "Exit 1 when the outcome is not complete.",
     "Exit 2 on a configuration error.",
-    "Exit 130 when cancelled. A later run of this session resumes that execution.",
+    "Exit 6 when a cancelled role session reopened more than one execution and one exhausted verify.",
+    "Exit 130 when cancelled. session continue resumes that execution.",
 ];
 const RUN_SPLIT = "Pass --workflow for a workflow run, or --role for an agent run.";
 function registerSessionCommand(program, status) {
@@ -218,7 +219,7 @@ function registerSessionCommand(program, status) {
         .option("--prompt <prompt>", "Prompt text for a role run.")
         .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. A workflow run is already JSON.")
+        .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`)
         .action((options) => settle(status, () => runSessionCommand(options)));
     session
@@ -231,13 +232,13 @@ function registerSessionCommand(program, status) {
         .action((id, options) => settle(status, () => prepareWorkflowSession(findWorkspace(invocationCwdPath()), id, String(options.workflow), optionalText(options.prior))));
     const continueCommand = session
         .command("continue")
-        .description("Resume an active or blocked workflow session until it stops. Resets revision counts. --once dispatches one stage and does not reset them.")
+        .description("Resume a stopped workflow or role session. A workflow session runs until it stops and resets revision counts. --once dispatches one workflow stage and does not reset them.")
         .argument("<session>", "Session to resume.");
     addDispatchOptions(continueCommand, "Dispatch the next eligible stage once and do not reset revision counts. Without --once, continue resets them.");
     continueCommand
         .option("--reply <text>", "Reply for the blocked stage. The new execution prompt body is this text.")
         .option("--reply-file <file>", "Read the blocked stage's reply from this file.")
-        .addHelpText("after", `${exitText(LOOP_EXITS)}With --once:\n${exitText(STAGE_EXITS)}Examples:\n  migent session continue <session> --once\n  migent session continue <session> --reply "<reply>"\n  migent session continue <session> --stage plan --reply-file answer.md\n`)
+        .addHelpText("after", `Workflow session:\n${exitText(LOOP_EXITS)}With --once:\n${exitText(STAGE_EXITS)}Role session:\n${exitText(ROLE_EXITS)}Examples:\n  migent session continue <session>\n  migent session continue <session> --once\n  migent session continue <session> --reply "<reply>"\n  migent session continue <session> --stage plan --reply-file answer.md\n`)
         .action((id, options) => settle(status, () => continueSession(id, options)));
     session
         .command("repair")
@@ -290,15 +291,15 @@ function registerSessionCommand(program, status) {
     })));
     session
         .command("metrics")
-        .description("Print derived usage, time, and revision counts.")
-        .argument("[session]", "Session to measure. Omit to list sessions.")
+        .description("Print usage, time, and revision counts recorded for a completed workflow session.")
+        .argument("[session]", "Workflow session to read. Omit to list sessions that have metrics.")
         .option("--json", "Print one JSON object, or one object per line for a list.")
         .option("--workflow <id>", "With a list, keep sessions for this workflow.")
         .option("--status <status>", "With a list, keep sessions in this status.")
         .option("--limit <n>", "With a list, keep the newest n sessions.")
         .addHelpText("after", `${exitText([
         "Exit 0 after one session object, or one object per line. An empty list prints nothing.",
-        "Exit 2 when --json is missing, the session has no events.jsonl, or a list flag is invalid.",
+        "Exit 2 when --json is missing, the session has no metrics.json, that file is corrupt, or a list flag is invalid.",
     ])}Examples:\n  migent session metrics <session> --json\n  migent session metrics --json --workflow <id> --status completed --limit 10\n`)
         .action((id, options) => settle(status, () => runSessionMetrics(findWorkspace(invocationCwdPath()), id, {
         asJson: options.json === true,
@@ -393,7 +394,6 @@ function workflowFlagsPresent(options) {
     return (options.once === true ||
         options.stage !== undefined ||
         options.prior !== undefined ||
-        options.attempts !== undefined ||
         options.maxDispatches !== undefined ||
         options.unlimitedDispatches === true ||
         options.progress === true ||
@@ -418,7 +418,6 @@ function runWorkflowCommand(args) {
             sessionId,
             startPrepared: args.prepared,
             priorSessionId: optionalText(args.options.prior),
-            maxAttempts: attemptsOf(args.options),
             maxDispatches: ceiling,
             refreshWorkflow: args.options.refreshWorkflow === true,
             ...outputFlags(args.options),
@@ -432,7 +431,6 @@ function runWorkflowCommand(args) {
         stageId,
         startPrepared: args.prepared,
         priorSessionId: optionalText(args.options.prior),
-        maxAttempts: null,
         maxDispatches: null,
         refreshWorkflow: args.options.refreshWorkflow === true,
         ...outputFlags(args.options),
@@ -443,6 +441,9 @@ function continueSession(session, options) {
         printError("--stage is empty.");
         return 2;
     }
+    const workspace = findWorkspace(invocationCwdPath());
+    if (isAgentSession(workspace, session))
+        return continueRoleSession(workspace, session, options);
     if (rejectOnce(options))
         return 2;
     const reply = readReply(options);
@@ -455,8 +456,8 @@ function continueSession(session, options) {
             sessionId: session,
             stageId,
             priorSessionId: optionalText(options.prior),
-            maxAttempts: null,
             maxDispatches: null,
+            continueFailed: true,
             refreshWorkflow: options.refreshWorkflow === true,
             reply,
             ...outputFlags(options),
@@ -469,13 +470,57 @@ function continueSession(session, options) {
         action: "continue",
         sessionId: session,
         priorSessionId: optionalText(options.prior),
-        maxAttempts: attemptsOf(options),
         maxDispatches: ceiling,
+        continueFailed: true,
         refreshWorkflow: options.refreshWorkflow === true,
         reply,
         ...outputFlags(options),
     });
 }
+function isAgentSession(workspace, sessionId) {
+    try {
+        requireAgentSession(workspace, sessionId);
+        return true;
+    }
+    catch (error) {
+        if (!(error instanceof ConfigurationError))
+            throw error;
+        if (error.message === `Session not found: ${sessionId}.`)
+            return false;
+        if (error.message === `Session ${sessionId} was not created by agent.`)
+            return false;
+        if (error.message.startsWith("Session status file is corrupt:"))
+            return false;
+        throw error;
+    }
+}
+function continueRoleSession(workspace, sessionId, options) {
+    const flags = [];
+    if (options.once === true)
+        flags.push("--once");
+    if (options.stage !== undefined)
+        flags.push("--stage");
+    if (options.prior !== undefined)
+        flags.push("--prior");
+    if (options.maxDispatches !== undefined)
+        flags.push("--max-dispatches");
+    if (options.unlimitedDispatches === true)
+        flags.push("--unlimited-dispatches");
+    if (options.progress === true)
+        flags.push("--progress");
+    if (options.verbose === true)
+        flags.push("--verbose");
+    if (options.refreshWorkflow === true)
+        flags.push("--refresh-workflow");
+    if (flags.length > 0) {
+        printError(`Session ${sessionId} is a role session. Omit ${flags.join(", ")}.`);
+        return 2;
+    }
+    const reply = readReply(options);
+    if (reply === "invalid")
+        return 2;
+    return continueAgent(workspace, { sessionId, reply });
+}
 function readReply(options) {
     const hasReply = options.reply !== undefined;
     const hasFile = options.replyFile !== undefined;
@@ -518,7 +563,6 @@ function addDispatchOptions(command, onceDescription) {
         .option("--once", onceDescription)
         .option("--stage <stage>", "Dispatch this ready stage once. It does not have to be the first ready stage.")
         .option("--prior <session>", PRIOR_HELP)
-        .option("--attempts <count>", "Failed executions allowed for one stage. Default: 3.")
         .option("--max-dispatches <count>", `Stage dispatches allowed in this command. Default: ${DEFAULT_MAX_DISPATCHES}. Pass --unlimited-dispatches to remove the ceiling.`)
         .option("--unlimited-dispatches", "Remove the dispatch ceiling for this command.")
         .option("--progress", PROGRESS_HELP)
@@ -526,7 +570,7 @@ function addDispatchOptions(command, onceDescription) {
         .option("--refresh-workflow", "Use the current workflow, models, and role instructions for this session. Requires an existing session that has a frozen workflow.");
 }
 function outputFlags(options) {
-    return { verbose: options.verbose === true, itemProgress: options.progress === true };
+    return { itemProgress: options.progress === true };
 }
 function showHelpWhenBare(status, command) {
     command.action(() => {
@@ -590,10 +634,6 @@ function rejectOnce(options) {
     if (options.once !== true && options.stage === undefined)
         return false;
     const flag = options.once === true ? "--once" : "--stage";
-    if (options.attempts !== undefined) {
-        printError(`${flag} cannot be combined with --attempts.`);
-        return true;
-    }
     if (options.maxDispatches !== undefined) {
         printError(`${flag} cannot be combined with --max-dispatches.`);
         return true;
@@ -617,12 +657,6 @@ function dispatchCeiling(options) {
         return DEFAULT_MAX_DISPATCHES;
     return integerFlag(maxDispatches, "--max-dispatches");
 }
-function attemptsOf(options) {
-    const raw = optionalText(options.attempts);
-    if (raw === null)
-        return 3;
-    return integerFlag(raw, "--attempts");
-}
 function integerFlag(raw, flag) {
     if (!/^[0-9]+$/.test(raw) || Number(raw) < 1) {
         throw new ConfigurationError(`${flag} must be at least 1.`);

package/dist/templates/migent/SKILL.md

@@ -6,166 +6,164 @@ description: Set up Migent in a project, or configure, run, inspect, and resume
 # Migent
 
 Migent runs a project's multi-stage agent workflows from the `migent` CLI.
-A workflow is a set of stages; each stage runs a role; a role uses a model
-name defined in `.migent/config.yaml`. Each run is a session.
-
-## Working rules
-
-- For an existing project, work from the root containing
-  `.migent/config.yaml`.
-- Read `.migent/config.yaml` and the relevant file under
-  `.migent/workflows/` before changing or running a workflow.
-- Before writing `.migent/config.yaml` or a file under `.migent/workflows/`,
-  read `.agents/skills/migent/references/schema-config.yaml` and
-  `.agents/skills/migent/references/schema-workflow.yaml`. They list every
-  accepted key. A key absent from those files is ignored.
-- Run `migent doctor --json` after editing configuration or workflows. If it
-  reports an outdated schema, run `migent migrate --yes`. Pass `--json` on
-  `config model` and `config role` writes too. The object includes the doctor
-  result.
+A workflow is a set of stages. A stage runs a role, or runs `verify` alone when `role` is omitted. A role uses a model name
+defined in `.migent/config.yaml`. Each run is a session, stored under
+`.migent/sessions/<session-id>/`.
+
+This skill is already in the prompt. Do not open its file again.
+
+## Rules
+
+- Work from the project root, the directory containing `.migent/config.yaml`.
+- Read `.migent/config.yaml` and the relevant `.migent/workflows/` file before
+  running a workflow.
+- Before writing either, read `.agents/skills/migent/references/schema-config.yaml`
+  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`.
 - 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.
-- Treat `.migent/sessions/` as generated, resumable state. Do not edit
-  `manifest.yaml`, `status.json`, `events.jsonl`, or files under
-  `executions/`. In a prepared session, write `task.md` and files next to
-  it before the first stage. Do not change `task.md` after that stage starts.
-- Preserve the user's task wording. Pass a one-line task in `--task`. Write
-  a longer task into `task.md` unchanged.
-- A workflow `session run` or `session continue` prints `session_id`,
-  `session_status`, `stop_reason`, `latest_decision`, and `outputs` on stdout.
-  Stderr carries stage boundaries and errors. A role run prints a table unless
-  `--json`. That JSON is the role result, not this object.
-- This skill is already in the prompt. Do not open its file again.
-- Do not read `task.md` or the documents it names. The stage agent reads
-  them. Still read `.migent/config.yaml` and the workflow file before starting.
-
-## Set up
-
-```
-migent init --no-input --provider <provider> --model <model-id> [--preset implement|plan] [--option KEY=VALUE] [--skill]
+- Do not edit generated session state: `manifest.yaml`, `status.json`,
+  `events.jsonl`, `metrics.json`, or anything under `executions/`.
+- Keep the user's task wording. Do not read `task.md` or the documents it
+  names; the stage agent does.
+- Never start a replacement session to reset limits or get past `blocked`.
+  Resume the same one.
+
+## Run a task
+
+`<workflow>` is a workflow id or a path to a workflow file.
+
+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`:
+
+```
+migent session prepare <some-id> --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.
+Then:
+
+```
+migent session run --session <some-id> --workflow <workflow>
+```
+
+Dispatch only one stage: add `--once`.
+
+### Read the result
+
+A workflow run prints plain lines on stderr and leaves stdout empty. It does
+not print JSON, and it does not print the stage report.
+
+- `session_id: <id>` when the session is created.
+- `stage <id> · attempt <n> · <HH:MM:SS> · <provider>/<model> (<options>).` when a stage starts. A description follows the model when the stage has one.
+- `stage <id> · attempt <n> · <duration> · <outcome>.` when it finishes. A decision is `decision=<value>` on that line.
+- A completed session adds `completed · <duration>` and one `artifact: <absolute-path>` line per published file. The path starts at the filesystem root and names the published file, so the suffix stays, such as `plan.md`. Report those paths.
+- Exit 1, 3, 6, and 8 also print `response: executions/<id>/response.md`. Read that file to see why it stopped.
+- Exit 7 prints `verify: executions/<id>/turns/01/verify.md`.
+- A session that stops before it is completed ends with `Resume with:` and `migent session continue <session-id>`.
+
+- Do not pass `--verbose` or `--progress`. Do not use `session follow`.
+- If the command runs in the background, wait for its completion notice. Do not
+  add a watcher that waits on the same exit.
+
+### Exit codes
+
+Read the exit code first. Exit 0 with `completed ·` is a completed session.
+Exit 0 without that line is `--once` after a complete stage.
+
+| Exit | Meaning | What to do |
+| --- | --- | --- |
+| 0 | Completed, or with `--once` the stage is complete | Report each `artifact:` path when the session completed. |
+| 1 | Blocked, or with `--once` the stage is not complete | If the stage line says `blocked`: read the `response:` path, then resume with the user's answer (below), or plain `session continue` once the blocker is fixed in the workspace. Otherwise `session continue` keeps going. |
+| 2 | Configuration error | Run `migent doctor --json`, fix config. |
+| 3 | A stage failed and the command did not wait | Read the `response:` path, fix the cause, `session continue`. Continue runs the stage and does not sleep until an old `retry_at`. |
+| 4 | A route would exceed `max_revisions` | Review why the stage keeps being revised, then `session continue` for another batch. |
+| 5 | `--max-dispatches` spent | `session continue` if more stages are appropriate. |
+| 6 | A stage's `verify` stayed red | Read the `response:` path, fix the cause, `session continue`. |
+| 7 | A stage with no role failed `verify` | Read the `verify:` path, fix the tree, `session continue`. That reruns the commands and does not open a provider. |
+| 8 | `--once` or `--stage` hit a provider quota and did not wait | Read the `response:` path. `session continue` runs the stage and does not sleep until the recorded `retry_at`. |
+| 130 | Cancelled, including a wait that was disarmed | Ask the user before resuming. Continue does not sleep until an old `retry_at`. |
+
+A stopped session that is not `completed` is resumable. Do not call it done.
+
+### Resume
+
+```
+migent session continue <session-id>
+```
+
+Same command for a workflow session and a role session. Read `session_status`, then use one row.
+
+| Kind | When | What to run |
+| --- | --- | --- |
+| Workflow | Not `completed`, including a blocker already fixed in the workspace | The command above. Runs until the session stops and resets revision counts. A blocked stage runs again. |
+| Workflow | The user answered a blocked stage | Add `--reply "<reply>"`. That text is the whole prompt body. |
+| Workflow | One stage, then stop | Add `--once`. Revision counts stay. |
+| Role | `cancelled` | The command above. The cut-off turn resumes in the same execution. Omit `--reply`. |
+| Role | `active` | The command above. The last prompt is sent again. |
+| Role | `blocked` | Add `--reply "<reply>"`. That is the next user turn. With no reply, the agent is only told to continue. |
+| Role | `completed` | Leave it stopped. Add `--reply` only to give a new turn. |
+
+`--reply-file <path>` is a longer reply. Pass only one of `--reply` and `--reply-file`. Do not pass `--once` or `--stage` on a role session.
+
+## Check a session
+
+```
+migent session show <session-id> --json
+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,
+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 init --no-input --provider <provider> --model <model-id> [--preset implement|plan] [--skill]
 migent doctor --json
 ```
 
-`--provider` and `--model` go together. `--preset` picks the workflow to
-create (default `implement`). `--skill` installs this skill at
-`.agents/skills/migent`; `migent skill update` refreshes a managed copy.
-
-## Run
-
-`migent session run` runs a workflow when `--workflow` is set, and one role
-when `--workflow` is omitted.
-
-- Start a one-line task: `migent session run --workflow <workflow> --task "<task>"`.
-  `<workflow>` is a workflow id, or a path to a workflow file (the `id`
-  field defaults to the file name). The sentence is stored in `task.md`.
-  `--task` must be one line. Runs until the session stops.
-- Start a longer task: `migent session prepare <some-id> --workflow <workflow>`.
-  `<some-id>` is a lowercase slug such as `wave-3` (letters, digits, and
-  single hyphens). Write `.migent/sessions/<some-id>/task.md`, then
-  `migent session run --session <some-id> --workflow <workflow>`.
-  `session continue` does not start a prepared session.
-- Start and dispatch one stage only: add `--once`. `--once` requires `--workflow`.
-- If the workflow's `requires` block names a prerequisite workflow and
-  decision, find it with
-  `migent session list --workflow <workflow-id> --status completed --json`
-  and pass `--prior <session-id>`. `session continue` accepts `--prior` too.
-- Resume an active workflow session: `migent session continue <session-id>`.
-  This resets revision counts. `migent session continue <session-id> --once`
-  advances one stage and does not reset them. A blocked session runs that stage
-  again. `migent session continue <session-id> --reply "<reply>"` sends the
-  reply as the new execution's prompt body. Use `--reply-file <path>` for a
-  longer reply. When more than one stage is blocked, pass `--stage`. Without
-  `--reply`, the prompt includes the blocker and the previous response.
-  A cancelled session is resumed the same way, on the same execution: a cut-off
-  provider turn is sent again, and a cut-off verify runs again. Ask the user
-  before resuming a cancellation.
-- Run one role: `migent session run --role <role> --prompt "<prompt>"`.
-  `roles.<role>.instructions` in config, when set, is prepended to that prompt.
-  Use `--file <path>` or `--stdin` for a long prompt. `--task` labels a new
-  role session and cannot be combined with `--session <session-id>`, which
-  continues an earlier role session. `--provider`/`--model` (together) and
-  `--option KEY=VALUE` override the role for this turn. Add `--json` for one
-  result object. Exit 0 means the outcome is complete, 1 not complete.
-- Read the JSON result on stdout for a workflow run. Do not pass `--verbose`
-  or `--progress`. `--verbose` inlines every stage response. `--progress`
-  prints each tool call.
-- Exit 1, 3, and 6 also include `latest_execution_id` and `response_path`,
-  relative to `.migent/sessions/<session-id>/`. Read that file when you must
-  fix the execution.
-- Stderr is not the outcome. Do not read the command log while a run is healthy.
-- When `session run` or `session continue` is in the background, wait for that
-  command's completion notice. Do not add a watcher that only waits for the same exit.
-- To check a run without waiting on the command, use
-  `migent session show <session-id> --json` once.
-- Do not run `session follow` or `--cursor`.
-
-Limits, accepted by workflow `session run` and by `session continue`:
-
-- `--attempts <n>`: failed executions allowed for one stage (default 3). On
-  `session continue` it sets a new total, not extra retries.
-- `--max-dispatches <n>`: stage dispatches allowed in this command (default
-  20). `--unlimited-dispatches` removes the ceiling; use it only if the user
-  agrees.
-
-### Exit codes and stop reasons
-
-A workflow result on stdout includes `stop_reason`. Read the exit code first.
-
-| Exit | Meaning | `stop_reason` | Session | What to do |
-| --- | --- | --- | --- | --- |
-| 0 | Completed (with `--once`: stage complete) | | completed or advancing | Report outputs. |
-| 1 | Blocked (with `--once`: stage not complete) | `blocked`, or `stage` with `--once` | blocked, or active with `--once` | When `stop_reason` is `blocked`, read `response_path`. Pass the user's words with `session continue --reply`, or `session continue` without `--reply` after the blocker is fixed in the workspace. When `stop_reason` is `stage`, `session continue` keeps going. |
-| 2 | Configuration error | | unchanged | Run `migent doctor --json`, fix config. |
-| 3 | `--attempts` spent | `retry_exhausted` | active | Read `response_path`, fix the cause, then `session continue` (add `--attempts` for a higher total). |
-| 4 | A route would exceed `max_revisions` | `revisions_exhausted` | active | Review why the stage keeps being revised; `session continue` (without `--once`) resets counts for another batch. |
-| 5 | `--max-dispatches` spent | `dispatch_limit` | active | `session continue` the same session if more stages are appropriate. |
-| 130 | Cancelled | | see snapshot | Ask the user before resuming. `session continue` resumes that same execution. |
-
-A stopped active session is resumable; do not describe it as completed. A
-blocked session is resumed the same way: `session continue` runs that stage
-again. Do not start a replacement session to reset limits or to get past
-`blocked`. If you change a workflow or
-config while a session is active, that session keeps the workflow, models, and
-role instructions it started with. Run `migent doctor --json` and tell the user.
-`migent session continue <session-id> --refresh-workflow` adopts the current
-workflow, models, and role instructions. `session run --session <id> --workflow <workflow> --refresh-workflow`
-does the same when starting a prepared session.
-
-## Inspect sessions
-
-- Newest match: `migent session list --latest --json`. Add `--workflow <id>` and
-  `--status active|prepared|completed|blocked|cancelled` to narrow it. `--limit <n>`
-  returns the newest n rows. Do not combine `--latest` with `--limit`.
-- `--latest --json` is one object, or `null` when nothing matches. A list is
-  a JSON array. Snapshot: `migent session show <session-id> --json` has the
-  status, latest execution, decision, and outputs. JSON omits the task text.
-- Compare runs with `migent session metrics --json`. One session is one
-  object. Several sessions are one object per line, newest first.
-  `--workflow`, `--status`, and `--limit` match `session list`. Read
-  `usage_missing` and `uncaptured_turns` before comparing totals.
-  `stage_attempt` is not a retry count.
-- `session follow` streams the event trace for a person at a terminal.
-  Do not use it or `--cursor` to coordinate a run.
-
-Report the session ID, status, stop reason, decisions, and published outputs
-that matter to the user. Published output paths are relative to
-`.migent/sessions/<session-id>/`; use the paths Migent reports instead of
-guessing.
-
-## Configure models and roles
-
-- Show: `migent config` or `migent config show`.
-- List models or roles: `migent config model --json`,
-  `migent config role --json`.
-- Change a model name:
-  `migent config model <name> --provider <provider> --model <model-id> --no-input --json`.
-  This updates every role and stage that uses the name. Use
-  `--option KEY=VALUE` and `--clear-option KEY` for provider options.
-- Point roles at an existing model name:
-  `migent config role <role>... --model-name <name> --no-input --json`. The value is
-  a name from `models`, not a provider model id.
-- Override one role without touching the shared name:
-  `migent config role <role> --provider <provider> --model <model-id> --no-input --json`.
-- `roles.<name>.instructions` is an optional list of strings. A stage prompt
-  includes it before that stage's instructions. A role run prepends it to the prompt.
+`--provider` and `--model` go together. The default preset is `implement`.
+`--skill` installs this skill; `migent skill update` refreshes it.
+
+## Change models
+
+Edit a model name (updates every role and stage that uses it):
+
+```
+migent config model <name> --provider <provider> --model <model-id> --no-input --json
+```
+
+Show the config with `migent config`, `migent config model --json`, or
+`migent config role --json`.
+
+## Look up anything else
+
+This skill covers the common path. Every command takes `--help`; use it before
+guessing a flag:
+
+```
+migent --help
+migent session run --help
+```
+
+References, read only when the task needs them:
+
+| File | Read when |
+| --- | --- |
+| `references/schema-config.yaml`, `references/schema-workflow.yaml` | Writing config or a workflow. |
+| `references/sessions.md` | Prerequisite session (`--prior`), several blocked stages (`--stage`), resuming a cancelled session, raising limits, adopting workflow edits (`--refresh-workflow`). |
+| `references/config.md` | Running one role, pointing roles at another model, overriding one role, role instructions. |
+| `references/inspect.md` | Filtering `session list`, comparing runs with `session metrics`, `session follow`. |
+
+All paths are under `.agents/skills/migent/`.

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

@@ -0,0 +1,52 @@
+# Roles and model configuration
+
+Write commands take `--no-input --json`. The JSON includes the doctor result.
+
+## Run one role
+
+Without `--workflow`, `session run` runs a single role:
+
+```
+migent session run --role <role> --prompt "<prompt>"
+```
+
+| Flag | Meaning |
+| --- | --- |
+| `--file <path>`, `--stdin` | Supply a long prompt. |
+| `--task` | Labels a new role session. Cannot be combined with `--session`. |
+| `--session <session-id>` | Sends a new prompt to an earlier role session. `session continue <session-id>` resumes a stopped role session. |
+| `--provider`, `--model` | Override the role for this turn. Pass together. |
+| `--option KEY=VALUE` | Override a provider option for this turn. |
+| `--json` | Print one result object (the role result, with `outcome_status`; not the workflow result). |
+
+Without `--json` it prints a table. Exit 0 means the outcome is complete, 1
+not complete. `roles.<role>.instructions`, when set, is prepended to the prompt.
+
+## Model names
+
+Provider options on a model name: `--option KEY=VALUE` to set,
+`--clear-option KEY` to remove.
+
+```
+migent config model <name> --provider <provider> --model <model-id> --no-input --json
+```
+
+## Point roles at an existing model name
+
+The value is a name from `models`, not a provider model id.
+
+```
+migent config role <role>... --model-name <name> --no-input --json
+```
+
+## Override one role without touching the shared name
+
+```
+migent config role <role> --provider <provider> --model <model-id> --no-input --json
+```
+
+## Role instructions
+
+`roles.<name>.instructions` is an optional list of strings. A stage prompt
+includes it before that stage's instructions. A role run prepends it to the
+prompt.

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

@@ -0,0 +1,32 @@
+# Inspecting many sessions
+
+For one session use `migent session show <session-id> --json` (SKILL.md).
+
+## List
+
+```
+migent session list --workflow <id> --status completed --limit 5 --json
+```
+
+- Output is a JSON array. `--latest` gives one object, or `null`; do not
+  combine it with `--limit`.
+- `--status` is one of `active|prepared|completed|blocked|cancelled|corrupt`.
+  A session whose `status.json` does not parse is listed as `corrupt`.
+- JSON rows omit the task text.
+
+## Metrics
+
+```
+migent session metrics --json
+```
+
+- One session prints its `metrics.json`. Several print one object per
+  line, newest first. Only a completed session has this file. `--workflow`,
+  `--status`, and `--limit` filter those rows.
+- Read `usage_missing` and `uncaptured_turns` before comparing totals.
+- `stage_attempt` is not a retry count.
+
+## Follow
+
+`session follow` streams the event trace for a person at a terminal. Do not use
+it or `--cursor` to coordinate a run.