@yaag/extension 0.7.0 → 0.8.1

package/README.md

@@ -5,6 +5,16 @@ The yaag pi extension: run Orchestration Programs from a pi session.
 It is loaded by pi through jiti, in **Node**, and bridges to the `yaag` CLI,
 which runs on **Bun** (ADR-0005, ADR-0015).
 
+## Docs
+
+The package ships the user and agent docs in `docs/`:
+
+- [`docs/getting-started.md`](docs/getting-started.md) — install, prerequisites, first Run.
+- [`docs/authoring.md`](docs/authoring.md) — how to write an Orchestration Program.
+- [`docs/examples.md`](docs/examples.md) — five example programs, in reading order.
+- [`docs/cli.md`](docs/cli.md) — CLI flags and tool parameters.
+- [`docs/troubleshooting.md`](docs/troubleshooting.md) — the errors you can meet.
+
 ## Prerequisites
 
 **Bun is required.** The extension itself runs in pi's Node process, but every

package/docs/authoring.md

@@ -0,0 +1,115 @@
+# Authoring an Orchestration Program
+
+A program is a TypeScript module. It default-exports `defineRun(...)`. It can
+import `@yaag/runtime` and `typebox`. A program file can import other modules;
+an inline program cannot.
+
+The deep reference is the vendored declaration file:
+`<program dir>/.yaag/types/runtime/index.d.ts`. This page gives the shape and
+the rules. It does not restate the types.
+
+## The Run
+
+`defineRun` takes a name, an optional description, an optional argument schema,
+and a `run` body. The body gets a context with `args` and `spawn`. What the body
+returns is the result of the Run.
+
+<!-- embed: docs/examples/01-minimal.ts -->
+
+```ts
+export default defineRun({
+  name: "minimal",
+  description: "Asks one Agent for one short answer.",
+  async run(ctx) {
+    const agent = await ctx.spawn({ name: "writer" });
+    return await agent.ask(prompt`Write one sentence about the sea. Report only that sentence.`);
+  },
+});
+```
+
+Keep the module top level side-effect free. `yaag describe` imports the module
+and executes its top level.
+
+## Arguments
+
+Declare arguments with a typebox object schema. The Orchestrator validates the
+arguments before it starts any Agent, so a bad call costs nothing. `ctx.args` is
+typed from the schema.
+
+<!-- embed: docs/examples/02-args.ts -->
+
+```ts
+  args: Type.Object({
+    topic: Type.String({ description: "What to write about" }),
+    sentences: Type.Optional(Type.Integer({ description: "How many sentences" })),
+  }),
+```
+
+## Agents and spawn restrictions
+
+`defineAgent` holds policy that does not change: the prompt, the model, the
+thinking level, the tools, and the skills. A spawn holds topology: the name, the
+working directory, and the worktree request. `ctx.spawn(definition, overrides)`
+puts the two together.
+
+`tools`, `disallowedTools`, `skills`, and `disallowedSkills` take **names**, not
+paths. `disallowedTools` and `disallowedSkills` apply last. An unknown skill
+name rejects the spawn.
+
+<!-- embed: docs/examples/03-fan-out.ts -->
+
+```ts
+const reviewer = defineAgent({
+  name: "reviewer",
+  tools: ["read"],
+  disallowedTools: ["yaag_run"],
+  skills: [],
+});
+```
+
+## Worktrees
+
+`worktree: true` puts the Agent in its own git worktree, on a fresh branch. Two
+Agents that write files then cannot collide. The worktree outlives the Run: yaag
+creates it and never removes it. Merge or delete the branch yourself.
+
+## Asks and limits
+
+`handle.ask(prompt, options)` is the only conversational verb. The soft limits
+are `maxTurns`, `maxToolCalls`, and `maxDurationMs`. A soft limit steers the
+Agent with `wrapUpPrompt`, gives it one more turn, then fails the Ask with
+`ASK_LIMIT`. The Handle stays alive, so the program can ask again.
+
+`timeoutMs` is different: it kills the Agent and fails with `ASK_TIMEOUT`. Use
+it as the last resort, not as a budget.
+
+`outputSchema` makes the Ask return data against a typebox object schema. A
+result that never validates fails with `ASK_INVALID_OUTPUT`.
+
+<!-- embed: docs/examples/04-controlled-ask.ts -->
+
+```ts
+      const report = await agent.ask(prompt`Read README.md and report your verdict.`, {
+        maxTurns: 6,
+        maxToolCalls: 12,
+        maxDurationMs: 120_000,
+        wrapUpPrompt: "Stop the work and report what you have now.",
+        outputSchema: Report,
+      });
+```
+
+Use the `prompt` tag for prompt text. It removes the indentation that a
+template literal keeps.
+
+## Asking the user
+
+An Agent cannot ask the user today. yaag cancels the dialog request of an Agent,
+so the Agent has to decide by itself. Write prompts that state the decision
+rules. ADR-0022 plans the human-in-the-loop verbs; they are not available yet.
+
+## Record and resume
+
+`--record <file>` writes a Cassette of every frame. `--resume <file>` runs the
+program again and replays the recorded Asks. A resume needs the program too,
+because a Cassette holds the history of a Run and never the program. See
+[Examples](examples.md#05--record-and-resume).

package/docs/cli.md

@@ -0,0 +1,105 @@
+# CLI and tool reference
+
+The `yaag` CLI and the yaag extension start the same Runs. The CLI is for a
+terminal; the tools are for a pi session.
+
+## Usage
+
+<!-- embed: @yaag/cli/src/argv.ts#USAGE -->
+
+```text
+usage:
+  yaag run <program.ts> [--quiet] [--args <json>] [--record <file>] [--replay <file>] [--resume <file>] [--events-fd <n>] [--config <file>] [--no-config]
+  yaag run --eval <source> [--quiet] [--args <json>] [--record <file>] [--replay <file>] [--resume <file>] [--events-fd <n>] [--config <file>] [--no-config]
+  yaag run --eval-fd <n> [--quiet] [--args <json>] [--record <file>] [--replay <file>] [--resume <file>] [--events-fd <n>] [--config <file>] [--no-config]
+  yaag describe <program.ts>
+  yaag setup-workspace [dir]
+
+--eval runs an Orchestration Program that you give as source text. Give a
+program file or --eval, but do not give both. A program that --eval runs can
+import "@yaag/runtime" and "typebox" only. A program that imports other modules
+must be a file.
+
+--eval-fd reads the program source from descriptor <n>, and needs the writer to
+close that descriptor. It keeps the source out of the process argument list,
+where every local user can read it. The yaag extension always uses it.
+
+--config <file> reads one more config file for this Run. Give it one time only.
+yaag reads it after the global config and after the project config.
+
+--no-config tells yaag to ignore the global config and the project config. It
+does not ignore --config.
+
+A --resume or --replay Run also needs the program: give the program file,
+--eval <source>, or --eval-fd <n>. A Cassette holds the history of a Run, and never the program
+to run.
+
+Warning: describe imports the module and executes its top level. Keep program module top level side-effect free.
+```
+
+A bad invocation prints this usage text on stderr and exits with code 2. Those
+argv errors have no troubleshooting entry: the usage text is the fix.
+
+The `--config` and `--no-config` flags select the config layers of a Run. See
+[Configuration](configuration.md#locations).
+
+## Tools
+
+### yaag_run
+
+Runs an Orchestration Program. It maps to `yaag run`.
+
+| field | maps to | notes |
+|---|---|---|
+| `file` | `yaag run <program.ts>` | Path of the program file. |
+| `script` | `--eval-fd` | Inline source. It can import `@yaag/runtime` and `typebox` only. |
+| `args` | `--args <json>` | A JSON object string. |
+| `background` | none | Extension only. Starts the Run and returns its Run id. |
+| `record` | `--record <file>` | Writes the Cassette here. |
+| `resume` | `--resume <file>` | Replays matching Asks, then continues live. |
+| `config` | `--config <file>` | Reads one more config file for this Run. |
+| `noConfig` | `--no-config` | Ignores the global config and the project config. |
+
+### yaag_status
+
+Reports the Runs of the session, or one Run.
+
+| field | maps to | notes |
+|---|---|---|
+| `id` | none | Extension only. Omit it for every Run of the session. |
+
+### yaag_stop
+
+Stops a background Run and reaps its Agents.
+
+| field | maps to | notes |
+|---|---|---|
+| `id` | none | Extension only. The Run id that `yaag_run` returned. |
+
+### yaag_describe
+
+Reports the name, description, and argument schema of a program. It maps to
+`yaag describe`.
+
+| field | maps to | notes |
+|---|---|---|
+| `file` | `yaag describe <program.ts>` | Describing imports the module and executes its top level. |
+
+### yaag_setup_workspace
+
+Creates `.yaag/` with the editor types. It maps to `yaag setup-workspace`.
+
+| field | maps to | notes |
+|---|---|---|
+| `dir` | `yaag setup-workspace [dir]` | Defaults to pi's working directory. |
+
+## Background Runs
+
+Only the extension has background Runs. Call `yaag_run` with `background: true`.
+It returns a Run id. Poll it with `yaag_status`, and end it with `yaag_stop`.
+A Run record outlives the session, so a later session reaches a Run by its id.
+
+## One side only
+
+- CLI only: `--replay` (strict replay, no model calls) and `--quiet`.
+- Extension only: `yaag_status`, `yaag_stop`, and background Runs.

package/docs/configuration.md

@@ -0,0 +1,87 @@
+# Configuration
+
+yaag reads up to three config files at the start of a Run. Their merged
+content is the configuration of that Run. yaag reads them one time, at Run
+start. A config edit during a Run changes nothing until the next Run.
+
+## Locations
+
+| Layer | Location |
+|---|---|
+| Global | `$YAAG_CONFIG_DIR/config.json` when `YAAG_CONFIG_DIR` is set. Else `$XDG_CONFIG_HOME/yaag/config.json` when `XDG_CONFIG_HOME` is an absolute path. Else `~/.config/yaag/config.json`. |
+| Project | `.yaag/config.json` in the Program Directory of the Run. |
+| Run | The file that `yaag run --config <file>` or the `config` option of the `yaag_run` tool gives. Give it one time only. |
+
+The Program Directory is the nearest directory that contains `.yaag/`. yaag
+searches upward from the directory of the program file. For an Inline Program,
+the search starts in the working directory.
+
+A global or project file that does not exist is an empty layer. A `--config`
+file that does not exist stops the Run at the start.
+
+## Supported fields
+
+A config file is plain JSON. [`examples/config.json`](examples/config.json)
+shows the full surface:
+
+<!-- embed: docs/examples/config.json -->
+
+```json
+{
+  "agents": {
+    "extensions": ["./extensions/team-conventions.ts", "npm:@acme/pi-guardrails"]
+  }
+}
+```
+
+| Field | Type | Effect |
+|---|---|---|
+| `agents.extensions` | array of strings | Extensions that every Agent of the Run loads, as extra `pi -e` arguments. |
+
+An entry is an extension path or an `npm:`/`git:` specifier. A relative path
+resolves against the directory of the config file that declares it. An `npm:`
+or `git:` specifier installs from the Agent working directory.
+
+Validation is strict. An unknown key, or a value with a wrong type, stops the
+Run at the start.
+
+## How the layers merge
+
+The extension lists concatenate in this order: global, then project, then run,
+then the `extensions` of the spawn call itself. yaag removes duplicates by
+resolved path. The first occurrence keeps its place. The merged list loads on
+top of the extensions a spawn call declares — a config never removes one.
+
+## Opt out
+
+`--no-config` (CLI) or `noConfig: true` (tool) makes the Run ignore the global
+config and the project config. It does not ignore an explicit `--config` file.
+Thus `--no-config --config ./one.json` gives the Run one known config file.
+
+`configExtensions: false` on one spawn call or one Agent Definition opts that
+one Agent out. The Agent then loads only the extensions its own call declares:
+
+<!-- embed: @yaag/runtime/src/types.ts -->
+
+```ts
+  /**
+   * Load the Effective Config's `agents.extensions` for this Agent. Default
+   * true; false spawns with only the extensions this call declares (ADR-0040).
+   */
+  readonly configExtensions?: boolean;
+```
+
+## Errors
+
+A config file that yaag cannot read or parse, or that fails validation, stops
+the Run at the start with exit code 1. The message names the file. See
+[A config file is missing or invalid](troubleshooting.md#a-config-file-is-missing-or-invalid).
+
+## Record and resume
+
+The Run record stores the `--config` path, never the file content. A
+`yaag_run` call that gives `resume` alone reads the stored path again, and
+yaag reads every layer again at that moment. An extension list that changed
+since the recording is a Divergence at the first spawn it changes: a strict
+replay stops there, and a resume goes live there. See
+[Replay or resume mismatch](troubleshooting.md#replay-or-resume-mismatch).

package/docs/examples/01-minimal.ts

@@ -0,0 +1,14 @@
+/**
+ * The smallest Orchestration Program. It starts one Agent, sends one Ask, and
+ * returns the text that the Agent reports.
+ */
+import { defineRun, prompt } from "@yaag/runtime";
+
+export default defineRun({
+  name: "minimal",
+  description: "Asks one Agent for one short answer.",
+  async run(ctx) {
+    const agent = await ctx.spawn({ name: "writer" });
+    return await agent.ask(prompt`Write one sentence about the sea. Report only that sentence.`);
+  },
+});

package/docs/examples/02-args.ts

@@ -0,0 +1,22 @@
+/**
+ * A Run with declared arguments. `yaag describe` shows the schema. The
+ * Orchestrator rejects invalid arguments before it starts an Agent.
+ */
+import { defineRun, prompt } from "@yaag/runtime";
+import { Type } from "typebox";
+
+export default defineRun({
+  name: "args",
+  description: "Writes about a topic, with a sentence budget.",
+  args: Type.Object({
+    topic: Type.String({ description: "What to write about" }),
+    sentences: Type.Optional(Type.Integer({ description: "How many sentences" })),
+  }),
+  async run(ctx) {
+    const sentences = ctx.args.sentences ?? 3;
+    const agent = await ctx.spawn({ name: "writer" });
+    return await agent.ask(
+      prompt`Write ${String(sentences)} sentences about ${ctx.args.topic}. Report only the text.`,
+    );
+  },
+});

package/docs/examples/03-fan-out.ts

@@ -0,0 +1,27 @@
+/**
+ * Parallel Agents from one Agent Definition. Each Agent gets the same spawn
+ * restrictions: it can read files, it cannot start a nested Run, and it has no
+ * skills.
+ */
+import { defineAgent, defineRun, prompt } from "@yaag/runtime";
+
+const reviewer = defineAgent({
+  name: "reviewer",
+  tools: ["read"],
+  disallowedTools: ["yaag_run"],
+  skills: [],
+});
+
+export default defineRun({
+  name: "fan-out",
+  description: "Reviews one file with three Agents at the same time.",
+  async run(ctx) {
+    const reviews = await Promise.all(
+      ["style", "risk", "tests"].map(async (topic) => {
+        const agent = await ctx.spawn(reviewer, { name: `reviewer-${topic}` });
+        return await agent.ask(prompt`Read README.md. Report the ${topic} problems you find.`);
+      }),
+    );
+    return reviews.join("\n\n");
+  },
+});

package/docs/examples/04-controlled-ask.ts

@@ -0,0 +1,33 @@
+/**
+ * An Ask with limits and a structured result. The limits steer the Agent first,
+ * then fail the Ask with `ASK_LIMIT`. The Agent stays alive, so the program can
+ * recover.
+ */
+import { defineRun, isYaagError, prompt } from "@yaag/runtime";
+import { Type } from "typebox";
+
+const Report = Type.Object({
+  verdict: Type.String(),
+  reasons: Type.Array(Type.String()),
+});
+
+export default defineRun({
+  name: "controlled-ask",
+  description: "Asks for a structured report under explicit limits.",
+  async run(ctx) {
+    const agent = await ctx.spawn({ name: "auditor", tools: ["read"] });
+    try {
+      const report = await agent.ask(prompt`Read README.md and report your verdict.`, {
+        maxTurns: 6,
+        maxToolCalls: 12,
+        maxDurationMs: 120_000,
+        wrapUpPrompt: "Stop the work and report what you have now.",
+        outputSchema: Report,
+      });
+      return `${report.verdict}: ${report.reasons.join("; ")}`;
+    } catch (error) {
+      if (isYaagError(error) && error.code === "ASK_LIMIT") return "the audit hit its limit";
+      throw error;
+    }
+  },
+});

package/docs/examples/05-record-resume.ts

@@ -0,0 +1,18 @@
+/**
+ * Two Asks in sequence. Run it with `--record` to write a Cassette. If the
+ * second Ask fails, run it again with `--resume` on that Cassette: the first
+ * Ask replays from the recording and costs nothing.
+ */
+import { defineRun, prompt } from "@yaag/runtime";
+
+export default defineRun({
+  name: "record-resume",
+  description: "Drafts a text, then shortens it.",
+  async run(ctx) {
+    const agent = await ctx.spawn({ name: "writer" });
+    const draft = await agent.ask(prompt`Write two sentences about rain. Report only the text.`);
+    return await agent.ask(
+      prompt`Shorten this text to one sentence: ${draft}. Report only that sentence.`,
+    );
+  },
+});

package/docs/examples/config.json

@@ -0,0 +1,5 @@
+{
+  "agents": {
+    "extensions": ["./extensions/team-conventions.ts", "npm:@acme/pi-guardrails"]
+  }
+}

package/docs/examples.md

@@ -0,0 +1,102 @@
+# Examples
+
+Five programs, in reading order. Each file is in `examples/` next to this page.
+Run one with `yaag run <file>`, or with the `yaag_run` tool.
+
+## 01 — one Agent, one Ask
+
+The smallest program. It starts one Agent, sends one Ask, and returns the text.
+The return value of `run` is the result of the Run.
+
+<!-- embed: docs/examples/01-minimal.ts -->
+
+```ts
+export default defineRun({
+  name: "minimal",
+  description: "Asks one Agent for one short answer.",
+  async run(ctx) {
+    const agent = await ctx.spawn({ name: "writer" });
+    return await agent.ask(prompt`Write one sentence about the sea. Report only that sentence.`);
+  },
+});
+```
+
+Full file: [`examples/01-minimal.ts`](examples/01-minimal.ts). Run it with
+`yaag run examples/01-minimal.ts`.
+
+## 02 — declared arguments
+
+A program declares its arguments with a typebox schema. `yaag describe` shows
+that schema, and the Orchestrator rejects invalid arguments before it starts an
+Agent.
+
+<!-- embed: docs/examples/02-args.ts -->
+
+```ts
+  args: Type.Object({
+    topic: Type.String({ description: "What to write about" }),
+    sentences: Type.Optional(Type.Integer({ description: "How many sentences" })),
+  }),
+```
+
+Full file: [`examples/02-args.ts`](examples/02-args.ts). Run it with
+`yaag run examples/02-args.ts --args '{"topic":"tides"}'`.
+
+## 03 — parallel Agents with restrictions
+
+An Agent Definition holds policy: which tools and which skills the Agent gets.
+A spawn holds topology: the name and the working directory. Three Agents run at
+the same time.
+
+<!-- embed: docs/examples/03-fan-out.ts -->
+
+```ts
+const reviewer = defineAgent({
+  name: "reviewer",
+  tools: ["read"],
+  disallowedTools: ["yaag_run"],
+  skills: [],
+});
+```
+
+Full file: [`examples/03-fan-out.ts`](examples/03-fan-out.ts). Run it with
+`yaag run examples/03-fan-out.ts`.
+
+## 04 — Ask limits and a structured result
+
+Soft limits steer the Agent first, then fail the Ask with `ASK_LIMIT`. The
+Agent stays alive, so the program can recover. An `outputSchema` makes the Ask
+return data instead of text.
+
+<!-- embed: docs/examples/04-controlled-ask.ts -->
+
+```ts
+      const report = await agent.ask(prompt`Read README.md and report your verdict.`, {
+        maxTurns: 6,
+        maxToolCalls: 12,
+        maxDurationMs: 120_000,
+        wrapUpPrompt: "Stop the work and report what you have now.",
+        outputSchema: Report,
+      });
+```
+
+Full file: [`examples/04-controlled-ask.ts`](examples/04-controlled-ask.ts). Run
+it with `yaag run examples/04-controlled-ask.ts`.
+
+## 05 — record and resume
+
+A Cassette records every frame of a Run. `--record <file>` writes it. `--resume
+<file>` runs the program again and replays the recorded Asks, so only the new
+work costs money. A resume needs the program too, because a Cassette never
+holds it.
+
+<!-- embed: docs/examples/05-record-resume.ts -->
+
+```ts
+    const agent = await ctx.spawn({ name: "writer" });
+    const draft = await agent.ask(prompt`Write two sentences about rain. Report only the text.`);
+```
+
+Full file: [`examples/05-record-resume.ts`](examples/05-record-resume.ts). Run
+it with `yaag run examples/05-record-resume.ts --record run.json`, then resume
+it with `yaag run examples/05-record-resume.ts --resume run.json`.

package/docs/getting-started.md

@@ -0,0 +1,54 @@
+# Getting started
+
+yaag runs Orchestration Programs: TypeScript modules that drive pi Agents.
+Start a Run from the `yaag` CLI, or from a pi session with the yaag extension.
+
+## Install
+
+Install the extension into a pi session:
+
+- `pi install @yaag/extension` adds it permanently.
+- `pi -e @yaag/extension` loads it for one session.
+
+yaag needs Bun on `PATH`. Install it with
+`curl -fsSL https://bun.sh/install | bash`. If the extension reports that Bun is
+missing, read [Bun is missing](troubleshooting.md#bun-is-missing).
+
+## Prepare the workspace
+
+Run the `yaag_setup_workspace` tool, or `yaag setup-workspace .` on the command
+line. It creates `.yaag/` in the workspace root. `.yaag/types/` holds the
+`@yaag/runtime` declarations that an editor needs. A folder with `.yaag/` is a
+Program Directory, and the extension tells the model about it.
+
+## Write and run the first program
+
+Copy [`examples/01-minimal.ts`](examples/01-minimal.ts) into the Program
+Directory:
+
+<!-- embed: docs/examples/01-minimal.ts -->
+
+```ts
+import { defineRun, prompt } from "@yaag/runtime";
+
+export default defineRun({
+  name: "minimal",
+  description: "Asks one Agent for one short answer.",
+  async run(ctx) {
+    const agent = await ctx.spawn({ name: "writer" });
+    return await agent.ask(prompt`Write one sentence about the sea. Report only that sentence.`);
+  },
+});
+```
+
+Then run `yaag run 01-minimal.ts`, or ask the model to use the `yaag_run` tool.
+`yaag describe 01-minimal.ts` reports the name, the description, and the
+argument schema of the program.
+
+## Next
+
+- [Authoring](authoring.md) — how to write a program.
+- [Examples](examples.md) — five programs, from minimal to record and resume.
+- [CLI reference](cli.md) — every flag and every tool parameter.
+- [Configuration](configuration.md#locations) — the three config files a Run reads.
+- [Troubleshooting](troubleshooting.md) — the errors you can meet.

package/docs/troubleshooting.md

@@ -0,0 +1,133 @@
+# Troubleshooting
+
+One entry for each failure you can meet. The quote is the message text, or the
+text that yaag matches on. An entry is at most ten lines, blank lines apart.
+
+## Bun is missing
+
+<!-- quote: src/process/status.ts -->
+
+> yaag needs Bun and could not find it on PATH or in ~/.bun/bin.
+
+Cause: the extension bridges to the Bun CLI, and Bun is not on `PATH` and not
+in `~/.bun/bin`.
+
+Fix: install Bun with `curl -fsSL https://bun.sh/install | bash`, then restart
+pi. The extension resolves Bun once, at load.
+
+## No API key for a spawned Agent
+
+<!-- quote: @yaag/runtime/src/model/model-failure.ts -->
+
+> No API key
+
+pi says `No API key found for the selected model.`, or `No API key for
+<provider>/<id>`. yaag reads that text and calls the failure `auth`.
+
+Cause: a spawned Agent is hermetic, so it loads no pi extension of the session.
+A model that a provider extension registers is out of reach.
+
+Fix: name the provider extension in the `extensions` spawn option, or give the
+Agent a model the machine can reach. A `model` list falls back on `auth`.
+
+## failed to publish cassette
+
+<!-- quote: @yaag/runtime/src/cassette/cassette-publish.ts -->
+
+> failed to publish cassette
+
+Cause: yaag could not write the Cassette. Most often the parent directory of
+the `--record` path does not exist, or it is not writable.
+
+Fix: create the directory first, then run again. The Run keeps its result; only
+the recording failed.
+
+## Replay or resume mismatch
+
+<!-- quote: @yaag/runtime/src/cassette/replay-divergence.ts -->
+
+> replay diverged for agent
+
+Cause: the program changed since the recording. A spawn option, an Agent
+Definition field, or an Ask prompt no longer hashes to the recorded value.
+
+Fix: restore the program to the recorded shape, or record again. A resume
+replays only the Asks that still match, and runs the rest live.
+
+## --resume or --replay needs the program
+
+<!-- quote: @yaag/cli/src/argv.ts -->
+
+> needs the program too: give <program.ts>, --eval <source>, or --eval-fd <n>.
+
+Cause: a Cassette holds the history of a Run. It never holds the program.
+
+Fix: name the program as well: `yaag run program.ts --resume run.json`.
+
+## Inline program limits
+
+<!-- quote: src/record/run-program-param.ts -->
+
+> yaag_run: script is too large
+
+Cause: an inline program (`script`, or `--eval`) must be 65536 bytes (64 KiB)
+or smaller, and it can import `@yaag/runtime` and `typebox` only.
+
+Fix: write the program to a file and pass `file` or `<program.ts>`. A file may
+import any module.
+
+## An Ask failed with a limit or a timeout
+
+<!-- quote: @yaag/runtime/src/errors.ts -->
+
+> limit reached at
+
+Cause: `ASK_LIMIT` is a tripped soft budget (`maxTurns`, `maxToolCalls`,
+`maxDurationMs`). `ASK_TIMEOUT` is `timeoutMs`, and it kills the Agent.
+`ASK_INVALID_OUTPUT` is a result that never satisfied `outputSchema`.
+`ASK_STALLED` is silence past the watchdog budget.
+
+Fix: raise the budget, or add a `wrapUpPrompt`. After `ASK_LIMIT` the Handle is
+alive, so the program can ask again.
+
+## describe executes the module top level
+
+<!-- quote: @yaag/cli/src/argv.ts -->
+
+> describe imports the module and executes its top level.
+
+Cause: `yaag describe` imports the program to read its declaration.
+
+Fix: keep the module top level side-effect free. Put every action inside `run`.
+
+## Missing @yaag/runtime editor types
+
+The editor says it cannot find the module `@yaag/runtime` in a program file.
+
+Cause: the folder is not a Program Directory yet, so `.yaag/types/` is absent.
+
+Fix: run the `yaag_setup_workspace` tool, or `yaag setup-workspace .`. It
+reports the written declarations:
+
+<!-- quote: @yaag/cli/src/setup-workspace.ts -->
+
+> .yaag/types/: written
+
+Rerun it after an upgrade to refresh the declarations.
+
+## A config file is missing or invalid
+
+<!-- quote: @yaag/runtime/src/config/config-file.ts -->
+
+> does not exist
+
+Cause: yaag reads the global config, the project config, and the `--config`
+file at the start of a Run. A `--config` file that is not there, or any config
+file that yaag cannot read or parse, stops the Run at the start (exit 1).
+
+Fix: correct the path or the file. Give `--no-config` to ignore the global
+config and the project config. [Configuration](configuration.md#locations)
+names the three locations and the supported fields.
+
+Plain usage errors of the CLI exit with code 2 and print the usage text. See
+[the CLI reference](cli.md#usage).

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@yaag/extension",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "publishConfig": {
     "access": "public"
   },
   "files": [
     "src",
+    "docs",
     "!src/**/*.test.ts"
   ],
   "type": "module",
@@ -24,9 +25,9 @@
   },
   "dependencies": {
     "@earendil-works/pi-tui": "^0.84.0",
-    "@yaag/cli": "0.7.0",
-    "@yaag/runtime": "0.7.0",
-    "@yaag/tui": "0.7.0",
+    "@yaag/cli": "0.8.1",
+    "@yaag/runtime": "0.8.1",
+    "@yaag/tui": "0.8.1",
     "nanoid": "^6.0.1"
   },
   "peerDependencies": {

package/src/docs/doc-embed.ts

@@ -0,0 +1,127 @@
+/**
+ * The drift guard behind every doc page: a fenced block must be a verbatim
+ * region of a real source file, and every block must name that file with an
+ * `<!-- embed: <source> -->` marker.
+ */
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { docPath } from "./docs-root.ts";
+
+/** One fenced block of a page, with the marker that precedes it. */
+export interface DocBlock {
+  /** The page the block came from, relative to the docs root. */
+  readonly page: string;
+  /** The marker payload, e.g. `docs/examples/01-minimal.ts` or `@yaag/cli/src/argv.ts#USAGE`. */
+  readonly source: string | null;
+  /** The block body, without the fences and without a trailing newline. */
+  readonly body: string;
+  /** 1-based line of the opening fence, for a self-explaining failure. */
+  readonly line: number;
+}
+
+const MARKER = /^<!--\s*embed:\s*(.+?)\s*-->$/;
+
+/** Reads every fenced block of a page, together with its preceding marker. */
+export function readBlocks(page: string): DocBlock[] {
+  const lines = readFileSync(docPath(page), "utf8").split("\n");
+  const blocks: DocBlock[] = [];
+  let marker: string | null = null;
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index] ?? "";
+    const found = MARKER.exec(line.trim());
+    if (found?.[1] !== undefined) {
+      marker = found[1];
+      continue;
+    }
+    if (!line.startsWith("```")) continue;
+    const body: string[] = [];
+    index += 1;
+    const open = index;
+    while (index < lines.length && !(lines[index] ?? "").startsWith("```")) {
+      body.push(lines[index] ?? "");
+      index += 1;
+    }
+    blocks.push({ page, source: marker, body: body.join("\n"), line: open });
+    marker = null;
+  }
+  return blocks;
+}
+
+/** Resolves a marker payload to the text it must match. */
+export function resolveSource(spec: string): string {
+  const [path, constant] = spec.split("#");
+  const text = readFileSync(resolvePath(path ?? ""), "utf8");
+  return constant === undefined ? text : exportedString(text, constant, spec);
+}
+
+function resolvePath(path: string): string {
+  if (path.startsWith("docs/")) return docPath(path.slice("docs/".length));
+  if (path.startsWith("src/")) return fileURLToPath(new URL(`../../${path}`, import.meta.url));
+  const require = createRequire(import.meta.url);
+  const packaged = /^(@yaag\/[a-z]+)\/(src\/.+)$/.exec(path);
+  if (packaged?.[1] === "@yaag/runtime" && packaged[2] !== undefined) {
+    // @yaag/runtime publishes one entry point, so reach its files through it.
+    const entry = require.resolve("@yaag/runtime");
+    return join(entry.slice(0, entry.lastIndexOf("/src/")), packaged[2]);
+  }
+  return require.resolve(path);
+}
+
+/** Reads the body of `export const NAME = \`…\`;` out of a source file. */
+function exportedString(text: string, name: string, spec: string): string {
+  const start = text.indexOf(`export const ${name} = \``);
+  if (start === -1) throw new Error(`${spec}: no exported template string named ${name}`);
+  const from = text.indexOf("`", start) + 1;
+  const to = text.indexOf("`;", from);
+  if (to === -1) throw new Error(`${spec}: ${name} is not terminated`);
+  return text.slice(from, to);
+}
+
+/** One quoted message of a page, with the source it is guarded against. */
+export interface DocQuote {
+  readonly source: string;
+  readonly text: string;
+}
+
+const QUOTE_MARKER = /^<!--\s*quote:\s*(.+?)\s*-->$/;
+
+/**
+ * Reads every `> quoted` line of a markdown text with the
+ * `<!-- quote: <source> -->` marker that precedes it.
+ *
+ * One marker guards one quote: the marker is consumed, so a quote can never be
+ * compared with the file of the entry above it. Throws when a quote line has no
+ * marker of its own.
+ */
+export function readQuotes(markdown: string): DocQuote[] {
+  const found: DocQuote[] = [];
+  let source: string | null = null;
+  for (const line of markdown.split("\n")) {
+    const marker = QUOTE_MARKER.exec(line.trim());
+    if (marker?.[1] !== undefined) {
+      source = marker[1];
+      continue;
+    }
+    if (!line.startsWith("> ")) continue;
+    if (source === null) throw new Error(`quoted message with no marker: ${line}`);
+    found.push({ source, text: line.slice(2).trim() });
+    source = null;
+  }
+  return found;
+}
+
+/** Fails unless the block body appears line for line inside its source. */
+export function assertVerbatim(block: DocBlock): void {
+  if (block.source === null) throw new Error(describe(block, "carries no embed marker"));
+  const source = resolveSource(block.source);
+  const body = block.body.replace(/\s+$/, "");
+  if (source.replace(/\r/g, "").includes(body)) return;
+  throw new Error(describe(block, `is not verbatim in ${block.source}`));
+}
+
+function describe(block: DocBlock, what: string): string {
+  const first = block.body.split("\n")[0] ?? "";
+  return `${block.page}:${block.line} (\`${first}\`) ${what}`;
+}

package/src/docs/docs-root.ts

@@ -0,0 +1,33 @@
+/**
+ * The shipped docs folder. The repo path is the tarball path, so one constant
+ * serves the system prompt, the error messages, and the drift guards.
+ */
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Absolute path of the shipped `docs/` folder, with no trailing separator. */
+export const DOCS_ROOT = fileURLToPath(new URL("../../docs", import.meta.url));
+
+/** The shipped pages, in reading order. */
+export const DOC_PAGES = [
+  "getting-started.md",
+  "authoring.md",
+  "examples.md",
+  "cli.md",
+  "configuration.md",
+  "troubleshooting.md",
+] as const;
+
+/** The five shipped example programs, in reading order. */
+export const EXAMPLE_FILES = [
+  "01-minimal.ts",
+  "02-args.ts",
+  "03-fan-out.ts",
+  "04-controlled-ask.ts",
+  "05-record-resume.ts",
+] as const;
+
+/** Absolute path of one shipped doc file, named relative to the docs root. */
+export function docPath(name: string): string {
+  return join(DOCS_ROOT, name);
+}

package/src/docs/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Public surface of the `docs/` module: where the shipped docs are, and the
+ * drift guard that keeps them true.
+ */
+export {
+  assertVerbatim,
+  type DocBlock,
+  type DocQuote,
+  readBlocks,
+  readQuotes,
+  resolveSource,
+} from "./doc-embed.ts";
+export { DOC_PAGES, DOCS_ROOT, docPath, EXAMPLE_FILES } from "./docs-root.ts";

package/src/process/run-argv.ts

@@ -15,6 +15,10 @@ export interface RunArgvOptions {
   readonly record?: string;
   /** Cassette path to resume from, forwarded as `--resume` (ADR-0014). */
   readonly resume?: string;
+  /** Run Config path, forwarded as `--config` (ADR-0040). */
+  readonly config?: string;
+  /** Suppresses the discovered config layers, forwarded as `--no-config` (ADR-0040). */
+  readonly noConfig?: boolean;
 }
 
 /**
@@ -35,5 +39,7 @@ export function runArgv(options: RunArgvOptions): readonly string[] {
     ...(options.args === undefined ? [] : ["--args", options.args]),
     ...(options.record === undefined ? [] : ["--record", options.record]),
     ...(options.resume === undefined ? [] : ["--resume", options.resume]),
+    ...(options.config === undefined ? [] : ["--config", options.config]),
+    ...(options.noConfig === true ? ["--no-config"] : []),
   ];
 }

package/src/process/spawn-run.ts

@@ -26,6 +26,10 @@ export interface StartRunOptions {
   readonly record?: string;
   /** Cassette path to resume from, forwarded as `--resume` (ADR-0014). */
   readonly resume?: string;
+  /** Run Config path, forwarded as `--config` (ADR-0040). */
+  readonly config?: string;
+  /** Suppresses the discovered config layers, forwarded as `--no-config` (ADR-0040). */
+  readonly noConfig?: boolean;
   /**
    * Called after each event is folded. `sequence` identifies this fd 3 stream
    * occurrence, not an event value or timestamp; it makes renderer observation
@@ -60,6 +64,8 @@ export function startRun(options: StartRunOptions): RunHandle {
     ...(options.args === undefined ? {} : { args: options.args }),
     ...(options.record === undefined ? {} : { record: options.record }),
     ...(options.resume === undefined ? {} : { resume: options.resume }),
+    ...(options.config === undefined ? {} : { config: options.config }),
+    ...(options.noConfig === true ? { noConfig: true } : {}),
   });
   const child = startCliChild({
     bun: options.bun,

package/src/process/status.ts

@@ -2,11 +2,14 @@
  * The one message the extension has to say about itself: either the bridge to
  * the Bun CLI is in place, or exactly what is missing and how to install it.
  */
+import { docPath } from "../docs/index.ts";
+
 export function statusReport(bun: string | null, cli: string): string {
   if (bun === null) {
     return (
       "yaag needs Bun and could not find it on PATH or in ~/.bun/bin. " +
-      "Install it with: curl -fsSL https://bun.sh/install | bash"
+      "Install it with: curl -fsSL https://bun.sh/install | bash. " +
+      `See ${docPath("troubleshooting.md#bun-is-missing")}`
     );
   }
   return `yaag ready — bun: ${bun}, cli: ${cli}`;

package/src/record/index.ts

@@ -2,7 +2,7 @@
  * Public surface of the `record/` module: the Run record registry, store, restore, and resume.
  * Files inside this directory import each other directly.
  */
-export { resolveProgramParams } from "./resume-source.ts";
+export { resolveLaunchConfig, resolveProgramParams } from "./resume-source.ts";
 export { mintRunId } from "./run-id.ts";
 export {
   confirmProgramTarget,

package/src/record/resume-source.ts

@@ -13,10 +13,12 @@ import type { RunRecord } from "./run-record.ts";
  * source it sees is byte-identical to the recorded one.
  */
 
-/** The stored Runs a resume lookup reads; a structural type, so a test needs no store. */
-export interface InlineSourceLookup {
+/** The stored Runs a resume reads back; a structural type, so a test needs no store. */
+export interface ResumeRecordLookup {
   /** The Inline Program source whose Run published `artifact`, or null. */
   inlineSourceFor(artifact: string): Promise<string | null>;
+  /** The Run Config path of the Run that published `artifact`, or null. */
+  resumeConfigFor(artifact: string): Promise<string | null>;
 }
 
 /**
@@ -32,18 +34,36 @@ export function pickInlineResumeSource(
 ): string | null {
   let found: string | null = null;
   for (const record of records) {
-    const { launch } = record;
-    if (launch.kind !== "inline") continue;
-    const { script, record: recorded } = launch;
-    const published = record.summary.artifact;
-    const matches =
-      (published !== null && published !== undefined && resolve(published) === artifact) ||
-      (recorded !== undefined && resolve(recorded) === artifact);
-    if (matches) found = script;
+    if (record.launch.kind !== "inline") continue;
+    if (publishes(record, artifact)) found = record.launch.script;
   }
   return found;
 }
 
+/**
+ * The stored Run Config path of the Run that published `artifact`, or null.
+ *
+ * Pure, and blind to the launch kind: a file Run and an inline Run both carry
+ * their Run Config path. The newest match wins, as above.
+ */
+export function pickResumeConfig(records: readonly RunRecord[], artifact: string): string | null {
+  let found: string | null = null;
+  for (const record of records) {
+    if (publishes(record, artifact)) found = record.launch.config ?? null;
+  }
+  return found;
+}
+
+/** Whether the Run of this record published, or wrote, the given Checkpoint. */
+function publishes(record: RunRecord, artifact: string): boolean {
+  const published = record.summary.artifact;
+  const recorded = record.launch.record;
+  return (
+    (published !== null && published !== undefined && resolve(published) === artifact) ||
+    (recorded !== undefined && resolve(recorded) === artifact)
+  );
+}
+
 /** What the tool says when no record holds the source of the given Checkpoint. */
 export function noStoredSourceMessage(artifact: string): string {
   return [
@@ -66,7 +86,7 @@ export function noStoredSourceMessage(artifact: string): string {
  */
 export async function resolveProgramParams(
   params: ProgramParams,
-  lookup: InlineSourceLookup,
+  lookup: ResumeRecordLookup,
 ): Promise<ProgramParams> {
   if (params.file !== undefined || params.script !== undefined) return params;
   if (params.resume === undefined) return params;
@@ -75,3 +95,28 @@ export async function resolveProgramParams(
   if (source === null) throw new Error(noStoredSourceMessage(artifact));
   return { ...params, script: source };
 }
+
+/** The launch parameters a resume needs, with the stored Run Config supplied. */
+export interface LaunchParams {
+  readonly resume?: string;
+  readonly config?: string;
+  readonly noConfig?: boolean;
+}
+
+/**
+ * The Run Config path a resume inherits from its Run record.
+ *
+ * A call that gives `config`, or `noConfig: true`, states its own layers, so it
+ * passes through untouched. `noConfig: false` states nothing: it is the default,
+ * and it emits no `--no-config`, so it must not drop the stored path either. A call that gives `resume` alone repeats the layers of the
+ * Run it resumes: the path is stored, and every layer is read again now.
+ */
+export async function resolveLaunchConfig<T extends LaunchParams>(
+  params: T,
+  lookup: ResumeRecordLookup,
+): Promise<T & LaunchParams> {
+  if (params.config !== undefined || params.noConfig === true) return params;
+  if (params.resume === undefined) return params;
+  const config = await lookup.resumeConfigFor(resolve(params.resume));
+  return config === null ? params : { ...params, config };
+}

package/src/record/run-record.ts

@@ -22,6 +22,11 @@ export interface RunLaunchContext {
   readonly args?: string;
   readonly record?: string;
   readonly resume?: string;
+  /**
+   * The Run Config path the launch gave, never its contents: a resume reads
+   * every layer again at resume time (ADR-0040).
+   */
+  readonly config?: string;
 }
 
 /**
@@ -144,6 +149,7 @@ function launchContext(stored: Record<string, unknown>): RunLaunchContext {
     ...(typeof stored.args === "string" ? { args: stored.args } : {}),
     ...(typeof stored.record === "string" ? { record: stored.record } : {}),
     ...(typeof stored.resume === "string" ? { resume: stored.resume } : {}),
+    ...(typeof stored.config === "string" ? { config: stored.config } : {}),
   };
 }
 

package/src/record/run-registry.ts

@@ -1,6 +1,6 @@
 import type { RunSummary, RunOutcome as SummaryOutcome } from "@yaag/runtime";
 import type { ProcessIdentity, RunOutcome } from "../process/index.ts";
-import { pickInlineResumeSource } from "./resume-source.ts";
+import { pickInlineResumeSource, pickResumeConfig } from "./resume-source.ts";
 import { type RunLaunch, type RunRecord, startedRecord } from "./run-record.ts";
 import { restoreRecords } from "./run-restore.ts";
 import { failedSummary, settledRecord } from "./run-settle-record.ts";
@@ -229,6 +229,16 @@ export class RunRegistry {
     return pickInlineResumeSource(await this.#store.load(), artifact);
   }
 
+  /**
+   * The Run Config path a Checkpoint resumes with, read back from the durable
+   * records (ADR-0040). Null when no record holds one. Same wait as above.
+   */
+  async resumeConfigFor(artifact: string): Promise<string | null> {
+    if (this.#store === undefined) return null;
+    await this.#store.settled();
+    return pickResumeConfig(await this.#store.load(), artifact);
+  }
+
   /** Reads a Run this session never started back from the store, by id. */
   async recall(id: string): Promise<RunStatus> {
     const known = this.lookup(id);

package/src/testing/run-call-render.ts

@@ -16,6 +16,8 @@ export interface RunParams {
   readonly background?: boolean;
   readonly record?: string;
   readonly resume?: string;
+  readonly config?: string;
+  readonly noConfig?: boolean;
 }
 
 function renderCallComponent(params: RunParams, expanded: boolean) {

package/src/tool/run-tool.ts

@@ -35,6 +35,7 @@ import {
   mintRunId,
   observedSettlement,
   programTarget,
+  resolveLaunchConfig,
   resolveProgramParams,
 } from "../record/index.ts";
 
@@ -65,6 +66,12 @@ const parameters = Type.Object({
         "Resume from this Cassette: matching Asks replay free, then the Run continues live. For an inline Run, give resume with no file and no script, and yaag reuses the stored source",
     }),
   ),
+  config: Type.Optional(Type.String({ description: "Path to one more config file for this Run" })),
+  noConfig: Type.Optional(
+    Type.Boolean({
+      description: "Ignore the global config and the project config for this Run",
+    }),
+  ),
 });
 
 /** pi's own message channel, narrowed to what a background Run needs. */
@@ -121,6 +128,12 @@ const DESCRIPTION = [
   "pass its artifact as `resume` on the retry: Asks that already succeeded",
   "replay instantly and free, and the Run goes live where it diverges. Record",
   "the retry too (to a different path) to keep every attempt resumable.",
+  "",
+  "`config` gives one more config file to this Run. yaag reads it after the",
+  "global config and after the project config. `noConfig: true` tells yaag to",
+  "ignore the global config and the project config. It does not ignore `config`,",
+  "so `config` with `noConfig: true` gives the Run one known config. A config",
+  "file that is not there stops the Run at the start.",
 ].join("\n");
 
 /**
@@ -169,6 +182,9 @@ export function createRunTool(deps: RunToolOptions): ToolDefinition<typeof param
       // A resume with no file and no script takes its source from the Run
       // record, before the shape check, so the shape it produces is valid.
       const target = programTarget(await resolveProgramParams(params, registry));
+      // A resume that states no layers of its own repeats the layers of the Run
+      // it resumes; every layer is read again now, at resume time (ADR-0040).
+      const launch = await resolveLaunchConfig(params, registry);
       if (bun === null) throw new Error(statusReport(null, cli));
       const program = await confirmProgramTarget(target);
 
@@ -183,7 +199,7 @@ export function createRunTool(deps: RunToolOptions): ToolDefinition<typeof param
         cli,
         program,
         args: params.args,
-        ...cassetteOptions(params),
+        ...launchOptions(launch),
         id,
         registry,
         start,
@@ -217,16 +233,26 @@ export function createRunTool(deps: RunToolOptions): ToolDefinition<typeof param
 }
 
 /**
- * Cassette paths are `resolve`d here; the CLI owns every rule about them —
- * combinations, validation, refusals — and its own message surfaces on failure.
+ * Cassette and config paths are `resolve`d here; the CLI owns every rule about
+ * them — combinations, validation, refusals — and its own message surfaces on
+ * failure.
  */
-function cassetteOptions(params: { readonly record?: string; readonly resume?: string }): {
+function launchOptions(params: {
+  readonly record?: string;
+  readonly resume?: string;
+  readonly config?: string;
+  readonly noConfig?: boolean;
+}): {
   record?: string;
   resume?: string;
+  config?: string;
+  noConfig?: boolean;
 } {
   return {
     ...(params.record === undefined ? {} : { record: resolve(params.record) }),
     ...(params.resume === undefined ? {} : { resume: resolve(params.resume) }),
+    ...(params.config === undefined ? {} : { config: resolve(params.config) }),
+    ...(params.noConfig === true ? { noConfig: true } : {}),
   };
 }
 
@@ -259,6 +285,8 @@ function registeredRun(options: {
   readonly args?: string;
   readonly record?: string;
   readonly resume?: string;
+  readonly config?: string;
+  readonly noConfig?: boolean;
   readonly id: string;
   readonly registry: RunRegistry;
   readonly start: (options: StartRunOptions) => RunHandle;
@@ -273,6 +301,8 @@ function registeredRun(options: {
     args: options.args,
     record: options.record,
     resume: options.resume,
+    config: options.config,
+    noConfig: options.noConfig,
     onProgress: (summary, event, sequence) => {
       options.registry.progress(options.id, summary);
       options.store.ingest(options.id, { summary, event, sequence, id: options.id });
@@ -289,6 +319,10 @@ function registeredRun(options: {
     ...(options.args === undefined ? {} : { args: options.args }),
     ...(options.record === undefined ? {} : { record: options.record }),
     ...(options.resume === undefined ? {} : { resume: options.resume }),
+    // The record stores the Run Config path, never its contents; a resume
+    // re-resolves every layer at resume time (ADR-0040). `noConfig` is not
+    // stored: it is a property of one launch, not of the Run's program.
+    ...(options.config === undefined ? {} : { config: options.config }),
   };
   const launch: RunLaunch =
     options.program.kind === "file"

package/src/tool/system-prompt-append.ts

@@ -1,3 +1,5 @@
+import { DOCS_ROOT } from "../docs/index.ts";
+
 /** Builds the host-visible yaag block appended to pi's system prompt. */
 export function yaagPromptBlock(directories: readonly string[]): string {
   const list = directories.join(", ");
@@ -26,6 +28,7 @@ export function yaagPromptBlock(directories: readonly string[]): string {
     "",
     "Full authoring surface (defineAgent, args schemas, ask limits, worktrees, model fallback):",
     "read `<program dir>/.yaag/types/runtime/index.d.ts`.",
+    `Shipped docs (${DOCS_ROOT}): getting-started.md, authoring.md, examples.md, cli.md, configuration.md, troubleshooting.md.`,
   ].join("\n");
 }
 

package/src/view/restored-run-text.ts

@@ -64,11 +64,14 @@ function resumeHint(record: RunRecord): string {
   // backslash, or a newline, and the hint must stay a call the model can copy.
   const resume = JSON.stringify(artifact);
   const { launch } = record;
+  // The Run Config path goes with the hint, so a copied call reads the same
+  // config layers the stopped Run read (ADR-0040).
+  const config = launch.config === undefined ? "" : `, config: ${JSON.stringify(launch.config)}`;
   switch (launch.kind) {
     case "inline":
-      return ` Resume it with yaag_run({ resume: ${resume} }) and no file and no script; yaag reuses the program source it stored.`;
+      return ` Resume it with yaag_run({ resume: ${resume}${config} }) and no file and no script; yaag reuses the program source it stored.`;
     case "file":
-      return ` Resume it with yaag_run({ file: ${JSON.stringify(launch.file)}, resume: ${resume} }).`;
+      return ` Resume it with yaag_run({ file: ${JSON.stringify(launch.file)}, resume: ${resume}${config} }).`;
     default: {
       const never: never = launch;
       return never;