@yaag/extension 0.6.2 → 0.8.0

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
@@ -138,6 +148,8 @@ export default defineRun({
   run: async (ctx) => {
     const agent = await ctx.spawn({
       name: "reviewer",
+      model: ["anthropic/claude-opus-4:medium", "anthropic/claude-haiku-4"],
+      thinking: (model) => (model.includes("haiku") ? "low" : "high"),
       tools: ["read", "grep"],
       disallowedTools: ["yaag_run"],
       skills: ["review"],
@@ -173,6 +185,14 @@ is recoverable and the Handle can be asked again. `wrapUpPrompt` replaces the
 default steering message. This is intentionally different from `timeoutMs`, the
 destructive fallback that rejects with `ASK_TIMEOUT` and closes the Agent.
 
+`model` takes one pattern, an ordered list, or a function of the failures so
+far; `thinking` takes a level or a function of the settled model. A pattern can
+end with a thinking suffix (`"opus-5:medium"`), and the suffix wins over
+`thinking`. The fallback rules — trigger classes, retry, termination — are
+stated on the types in `<program dir>/.yaag/types/runtime/index.d.ts` and in
+the root [`README.md`](../../README.md#models-and-fallback); the sequences are
+in [`../../docs/architecture.md`](../../docs/architecture.md) §4 and §6.
+
 The tool call:
 
 ```json
@@ -231,3 +251,6 @@ Provided commands: `/yaag-status`, `/yaag-setup-workspace [dir]`.
 - [`../../docs/architecture.md`](../../docs/architecture.md) — the diagrams
 - [`../../docs/adr/`](../../docs/adr) — why it is built this way
 - [ADR-0018: foreign workspaces use CLI aliases and vendored types](../../docs/adr/0018-foreign-workspaces-use-cli-aliases-and-vendored-types.md) — workspace setup and foreign-program support
+- [ADR-0037: model resolution triggers are read from pi's stderr diagnostic](../../docs/adr/0037-model-resolution-triggers-are-read-from-pis-stderr-diagnostic.md) — which failures start a fallback
+- [ADR-0038: a mid-Ask model swap is a yaag-side match, then `set_model`](../../docs/adr/0038-a-mid-ask-model-swap-is-a-yaag-side-match-then-set-model.md) — how a live Agent changes model
+- [ADR-0039: replay adopts the recorded resolved model](../../docs/adr/0039-replay-adopts-the-recorded-resolved-model.md) — why a replay skips the resolution loop

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,102 @@
+# 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.
+
+## 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/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.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,53 @@
+# 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.
+- [Troubleshooting](troubleshooting.md) — the errors you can meet.

package/docs/troubleshooting.md

@@ -0,0 +1,132 @@
+# 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.
+
+Plain usage errors of the CLI exit with code 2 and print the usage text. See
+[the CLI reference](cli.md#usage).