# Your CLI is an agent tool

> Every burgee program answers --schema and --mcp from its one declaration — no tool definitions, no second interface.

Source: https://burgee.interlace.tools/docs/agent-surfaces

A burgee program is data first. The same manifest that renders `--help` answers two
questions an agent asks before anything else.

## `--schema` — the program as data

```bash
mytool --schema
```

Prints the commands, their arguments and options (with choices, defaults and which are
required), each command's `effects`, its examples, and a JSON Schema per command. It reads
the manifest and nothing else: no config file, no network, no handler runs (N8), so it is
safe to call first.

The document shows each option's default and env var, but not which of them a run used. So
just before `commands` it carries one line naming the flag that answers that:
`"explain":"--explain <option> on a command says where its value came from: default, env, config or flag"`.
Agents that read `--schema` without it spent three to eight turns probing the env var through
shell calls (D-20261009-b1-totals-and-explain). One command's schema (`mytool deploy --schema`)
does not carry it, and neither does `--schema` on `burgee/commander` or `burgee/yargs`, which
do not parse `--explain`.

`mytool schema` is the same request spelled as a subcommand — `schema deploy` and
`schema deploy --field options.region` print exactly what the flag forms print — because
that is where [clispec.dev](https://clispec.dev) and the agents that follow it look. A
program whose own `schema` command exists, or whose root command takes arguments, keeps the
word: burgee answers only the flag there. The root `--help` names `--schema`.

### It is also a clispec v0.3 document

The same document is a [The CLI Spec v0.3](https://clispec.dev) document
([its schema](https://clispec.dev/schema/v0.3.json)): the keys clispec defines sit beside
burgee's own, and `schemaVersion` stays 1, because none of burgee's keys changed meaning. Each
is read from what the program already declares.

| Key | What it says | Read from |
| :-- | :-- | :-- |
| `clispec` | `"0.3"` | — |
| `version` | the program's version, always | `defineProgram({ version })`, else the owning `package.json` |
| `errors` | every kind a run can fail with: `{ kind, exit_code, retryable, description }` | `ExitCode`, and each `defineError` class |
| `global_args` | the flags every command takes | the rows root help prints under `Global options:` |
| `output` | `{ "tty": "text", "piped": "text", "formats": [...] }`: text unless asked for, even under a pipe | — |
| a command's `example` | its first example as `{ "args": [...] }`, the program's name dropped | `examples` |
| a command's `cardinality`, `output_kind`, `media_type` | how much comes back, and what it is | `output: { cardinality, kind, mediaType }` |
| a command's `stdout_schema` | what `--json` prints: the envelope, with your result as its `data` | `output.schema`, else `fields` |

```js
defineCommand({
  name: 'list',
  effects: 'read_only',
  examples: [{ command: 'mytool list --json' }],
  output: { cardinality: 'bounded', schema: { type: 'array', items: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] } } },
  run: () => [{ id: 'a' }], // TypeScript holds this to output.schema
});
```

A runnable command with no `output.cardinality` makes `burgee dev` print a warning, never an
error: clispec has no safe default for how much comes back. clispec's checker scores the
reference demo 24 / 24 ([Benchmarks](/docs/benchmarks)). Not carried: the `burgee/commander` and
`burgee/yargs` documents, whose `--schema` is built where their weight budgets have no room, and
the summary printed over the budget, which lists commands without what clispec requires of one.

## `--mcp` — the program as MCP tools

```bash
mytool --mcp
```

Serves the same manifest as [MCP](https://modelcontextprotocol.io) tools over stdio —
JSON-RPC 2.0, four methods (`initialize`, `ping`, `tools/list`, `tools/call`), no dependency outside the burgee family. A tool call runs the command exactly as a
`--json` caller would; the result is that envelope, byte for byte, so an agent reading
your CLI over MCP and one shelling out with `--json` see one payload.

### What becomes a tool

Every command that runs and is not hidden, named by its path — `config get` is
`config_get`, and a program whose root command runs (a single `run(defineCommand(…))`, or
a commander program with a root `.action()`) is named after the program. What keeps a
command out is a word its author wrote, never silence:

```ts
defineCommand({
  name: 'deploy',
  effects: 'non_idempotent', // read_only | idempotent | non_idempotent | withheld
  // …
});
```

- **On burgee's own API, `effects` is required.** `defineCommand` refuses a runnable
  command without it, so every tool carries MCP's `readOnlyHint`, `idempotentHint` and
  `destructiveHint`, generated from the declaration. `'withheld'` serves the command to
  people and keeps it out of `tools/list`.
- **On `burgee/commander` and `burgee/yargs`, a command that declared nothing is still a
  tool.** Neither incumbent has a notion of effects, so it is listed with
  `annotations: { effects: 'undeclared' }` and no hints — and MCP's defaults for absent
  hints (not read-only, destructive) are the reading a client applies. Declare it with
  `.effects('read_only')`, or keep it out with `.effects('withheld')`.

### Arguments

A tool's `inputSchema` has one property per argument and option. An option's property is
its declared key and names the flag it becomes — `"dryRun": { "type": "boolean", "flag":
"--dry-run" }` — and a tool call is turned back into exactly that flag. A boolean sent as
`false` is passed as `--no-<name>` when the option would otherwise be on (a `true` default
or an environment variable) and left out otherwise, so an agent that spells out every
`false` trips no relation. Under `burgee/commander`, a `--no-color` declared without a
`--color` is the property `noColor`.

### Results

The `--json` envelope, byte for byte. Under `burgee/commander`, `data` is what the action
**returned**: an action that prints instead gives `data: null`, because commander actions
return nothing. Return the value — `.action(() => ({ lines }))` — and it is `data`.
Printed output becomes the tool result: whatever a handler writes to stdout during a call
(`console.log`, `process.stdout.write`) is captured and follows the envelope as a second
text item, never a stray line on the JSON-RPC stream, and what it writes to stderr stays on
stderr.

The data comes back as data too. The result carries the envelope's `data` as
`structuredContent` beside the text, or its `error` on a failure, and wraps anything that is not
an object as `{ "result": … }`, because the protocol requires an object. A command that declares
`output.schema` lists it as the tool's `outputSchema`, wrapped the same way, so a client can
check the result against it; a command that declares none lists none, rather than a schema
guessed from one run. Text a handler printed instead of an envelope carries no
`structuredContent`, and the text is unchanged either way.

A handler that throws, rejects or throws something that is not an `Error` is an error
result, not a crashed server: `isError: true`, and the text is the `{ "ok": false, "error":
… }` envelope a `--json` caller gets on stdout. An `AuthError` carries `code` 5 (`"auth"` on
the commander and yargs front ends) with its `hint` and `fix`, and the server answers the
next call.

### Cancellation and progress

Calls are served concurrently, so a client can stop one while it runs. `notifications/cancelled`
aborts that call's `ctx.signal` with the reason `cancelled`, the same signal `--timeout` aborts:
hand it to `fetch`, a child process or anything else that takes a signal, and the work stops.
Its `ctx.onExit` handlers run once, and no response is sent for it. The server goes on serving.

`ctx.progress(done, total?, message?)` reports how far a command has got. When the client sent a
`progressToken` with the call, each report is a `notifications/progress` carrying it; a value that
does not rise above the last one is dropped, because the protocol requires progress to increase.
Anywhere else `ctx.progress` does nothing, so call it unconditionally:

```ts
run: async ({ signal, progress }) => {
  for (const [at, file] of files.entries()) {
    await upload(file, { signal });
    progress(at + 1, files.length, file);
  }
}
```

A bar from `flagstaff/progress` does the same on its own: inside a call that asked for progress, it
sends its count, with its static line (`12/30 files · 40%`) as the message, and draws nothing into
the result. Outside one it draws as it always has. The root `flagstaff` entry's `progress` always
draws, so the bridge costs nothing to a program that never serves MCP.

### Client configuration

For Claude Desktop, Claude Code, Cursor or any stdio client, register the program as a
server — nothing else to write. `--mcp --print-config` prints the block for the program you run
it on: its name, and the command that starts it. A program started as one of its package's bins
is started by that name, which is how an installed CLI is found on `PATH`; one started as
`node <file>` is started that way, with the file's full path. On Windows, where npm installs a
bin as a `.cmd` shim that a client cannot start directly, the bin is started through
`"command": "cmd", "args": ["/c", "demo-burgee", "--mcp"]`. For the reference demo, run as its
bin `demo-burgee` on Linux or macOS:

{/* mcp-config:start — `demo-burgee --mcp --print-config`, written by scripts/mcp-config-block.ts */}

```json
{
  "mcpServers": {
    "demo": {
      "command": "demo-burgee",
      "args": [
        "--mcp"
      ]
    }
  }
}
```

{/* mcp-config:end */}

Paste it into the client's configuration as it is. The block above is that command's output,
and a test starts the server from it and completes a tool call.

On `burgee/commander` and `burgee/yargs`, a program that declares its own `--schema` or
`--mcp` option keeps it, and burgee leaves it alone: the surfaces are additive, never a change
to a program that already exists. On burgee's own API the names are reserved, and
`defineCommand` refuses an option that redefines one.

## `--skill` — the program as an Agent Skill

```bash
mytool --skill                        # SKILL.md on stdout
npx burgee skill dist/index.js        # SKILL.md and AGENTS.md, beside the bin
npx burgee skill dist/index.js --check  # in CI: exit 1 when the committed files are stale
```

An [Agent Skill](https://agentskills.io/specification), projected from the same declaration:
front matter with a `name` and a `description` within the specification's limits, then what the
program is for, the contract an agent relies on (`--json` and its envelope, `--explain`, every
exit code with its error kind), and one line and the first example per command. It is small on
purpose: a command's options are behind `mytool --schema <command>`, which the skill names and
never inlines, so an agent pays for one command's contract when it uses that command.

`burgee skill` writes `SKILL.md` and `AGENTS.md` (the same body, no front matter) into the
directory of the `bin` your package.json names, unless `--out` says where. When an `AGENTS.md`
sits beside the binary or in the directory above it, the root help's line for agents names it;
without one, the line is unchanged. A root that declares its own `--skill` option keeps it.

## `completion <shell>` — static unless you ask

```bash
mytool completion zsh > "${fpath[1]}/_mytool"   # also: bash, fish, pwsh, fig
```

Commands, subcommands, options and choice values, with descriptions where the shell shows
them — generated from the same manifest, as plain shell. Pressing TAB does not execute the
program, with one exception you opt into: an option or a positional that declares `complete`
has its values asked for at TAB time, through `mytool __complete`. Each script is pinned by a
snapshot and exercised by its real shell in CI. The templates live in `burgee/completions` and
load only on that command, so a program pays for them when it prints a script, never at startup.

A completer is called as `complete(partial, context)`, and `context` is the rest of the line
before the cursor. It carries the command `path`, the `options` already typed (coerced the way a
run coerces them), the `positionals`, and `raw` for any value that failed coercion. So one value
can depend on another (yargs #793):

```ts
defineCommand({
  name: 'deploy',
  options: {
    remote: { type: 'string' },
    branch: { type: 'string', complete: (partial, { options }) => branchesOf(String(options.remote ?? 'origin')) },
  },
  arguments: [{ name: 'service', complete: () => services() }],
  effects: 'non_idempotent',
  run: ({ options, args }) => deploy(args.service, options),
});
```

The line is unfinished, so nothing is required, no relation is checked, and no env, config or
default is read on TAB. A completer that takes one parameter is called as it always was, and a
completer that throws offers nothing.

## `--explain <option>` — where a value came from

Every value a command sees comes from exactly one place, in one fixed order:
**flag > env > config file > package.json field > default**. `--explain` says which, and
what it beat:

```text
$ mytool deploy --explain region
region = "eu-1"   from config file ./mytool.config.json
         candidates: flag --region (unset), env MYTOOL_REGION (unset), default "us-1"
```

Every command that runs lists `--explain <option>` in its help, and the root help's `For
agents:` line names it beside `--schema` and `--json`. So do the `--schema` document and the
hint on an unknown command that matches nothing. The same information rides under `--json` as `meta.provenance`, per option — for an agent,
the difference between one call and five. `envPrefix` and `config: true` on
`defineProgram` opt a program into env names and config discovery; nothing is read that
the running command did not declare.

## Stopping instead of prompting

`ctx.interactive` is true only with a terminal on stdin, no `CI`, and no detected agent
(`AI_AGENT`, `CLAUDECODE`, `CURSOR_AGENT`, `CODEX_THREAD_ID`, `GEMINI_CLI`), terminal or not;
`FORCE_TTY=1` overrides. It is roundel's `interactive()`, the same rule caique's prompts ask. A
handler reads `ctx.interactive` and `ctx.agent`, and where it would have prompted it stops with
what the caller must do:

```ts
if (!ctx.interactive) ctx.actionRequired({
  reason: 'confirm',
  message: 'deploying to prod needs confirmation',
  next: [{ command: 'deploy --target prod --yes', when: 'once you have reviewed the plan' }],
});
```

The envelope carries `status: "action_required"`, the reason, and `next[]` as runnable
commands with the program in front and the caller's own `--json` carried; the exit code is
4. An idempotent command reports `changed: true | false`, and `--schema` summarises above
a character budget with `<command> --schema` to drill into one.

---

# burgee/brand

> Every export of burgee/brand, with its signature and doc comment: opposedField, burgeeFlagPath, fieldId, chargeTransform, chargeRotation, placeCharge and 8 more, plus 7 types.

Source: https://burgee.interlace.tools/docs/api/brand

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

burgee/brand — a brand declares itself once; every identity surface is that
declaration read by a different reader.

```ts
import { opposedField, burgeeFlagPath, fieldId, … } from 'burgee/brand';
```

## Functions

### burgeeBody

Field, charge and optional bordure — everything inside the viewBox.

```ts
function burgeeBody(brand: BurgeeBrand, id?: string, moving?: boolean): string;
```

| Parameter | Type |
| :-- | :-- |
| `brand` | `BurgeeBrand` |
| `id` (optional) | `string` |
| `moving` (optional) | `boolean` |

**Returns** `string`

### burgeeFlagPath

The flag silhouette, as SVG path data.

```ts
function burgeeFlagPath(): string;
```

**Returns** `string`

### chargeGroup

The two Interlace bars, rotated and placed as the charge.

```ts
function chargeGroup(colors: BurgeeColors, scale?: number): string;
```

| Parameter | Type |
| :-- | :-- |
| `colors` | `BurgeeColors` |
| `scale` (optional) | `number` |

**Returns** `string`

### chargeRotation

The angle the charge is rotated by, as an SVG transform.

```ts
function chargeRotation(): string;
```

**Returns** `string`

### chargeTransform

Where the charge sits, as an SVG transform. Exported because consumers that
hand-write the flag (a React component, say) must place it identically, and
recomputing it at the call site is how the two drift apart.

```ts
function chargeTransform(scale?: number): string;
```

| Parameter | Type |
| :-- | :-- |
| `scale` (optional) | `number` |

**Returns** `string`

### defineBurgee

Declare a brand. Everything on the returned object is a projection of it.

```js
const brand = defineBurgee({
  name: 'burgee',
  mark: { lead: '#a84c17', follow: '#0a6b47' },
  field: [
    { offset: 0, color: '#0a6b47' },
    { offset: 0.5, color: '#0a0a0a' },
    { offset: 1, color: '#a84c17' },
  ],
});
writeFileSync('icon.svg', brand.favicon());
```

```ts
function defineBurgee(brand: BurgeeBrand): Burgee;
```

| Parameter | Type |
| :-- | :-- |
| `brand` | `BurgeeBrand` |

**Returns** `Burgee`

### fieldId

A stable id for the field gradient, derived from the declaration.

```ts
function fieldId(brand: BurgeeBrand): string;
```

| Parameter | Type |
| :-- | :-- |
| `brand` | `BurgeeBrand` |

**Returns** `string`

### opposedField

The field two colours imply.

```ts
function opposedField(colors: BurgeeColors, ground?: string): FieldStop[];
```

| Parameter | Type |
| :-- | :-- |
| `colors` | `BurgeeColors` |
| `ground` (optional) | `string` |

**Returns** `FieldStop[]`

### placeCharge

Place any charge markup where the charge belongs, at the charge's scale.

```ts
function placeCharge(markup: string, scale?: number): string;
```

| Parameter | Type |
| :-- | :-- |
| `markup` | `string` |
| `scale` (optional) | `number` |

**Returns** `string`

## Constants

### BURGEE_ANGLE

```ts
const BURGEE_ANGLE: number;
```

### BURGEE_FLAG

```ts
const BURGEE_FLAG: readonly Point[];
```

### CHARGE

The charge occupies this fraction of the flag, and sits here within it.

```ts
const CHARGE: {
    readonly scale: 0.4;
    readonly x: 42;
    readonly y: 50;
};
```

### DEFAULT_GROUND

The midpoint a field falls through when none is given. Near-black.

```ts
const DEFAULT_GROUND = "#0a0a0a";
```

### FIELD_AXIS

The gradient axis: the direction the two bars are stacked on, traversed
backwards — hoist-top to fly-bottom, in mark-space coordinates.

```ts
const FIELD_AXIS: {
    readonly x1: 25;
    readonly y1: 6.7;
    readonly x2: 75;
    readonly y2: 93.3;
};
```

## Interfaces

### Bordure

One band of the outline.

```ts
interface Bordure {
    color: string;
    /** Visible thickness, in mark-space units. */
    width: number;
}
```

### Burgee

Everything one brand declaration projects into.

```ts
interface Burgee {
    /** The flag alone, square, at any size. */
    flag(size?: number): string;
    /**
     * The same mark with its sheen sweeping across it, for a page that can afford
     * motion — a site header, a docs hero. Identical to {@link Burgee.flag} when
     * no `sheen` is declared, and parked still under `prefers-reduced-motion`.
     */
    alive(size?: number): string;
    /** Favicon master. One file serves both themes — the flag carries its own field. */
    favicon(size?: number): string;
    /** Social card, 1200×630. */
    og(options?: CardOptions): string;
    /** Article cover, 1000×420. */
    cover(options?: CardOptions): string;
    /** Flag and wordmark, laid out horizontally. */
    lockup(options?: CardOptions): string;
    /** The gradient id this brand emits, for callers that need to match it. */
    fieldId(): string;
}
```

### BurgeeBrand

```ts
interface BurgeeBrand {
    /** Accessible name for the flag. Without one the flag is decorative. */
    name?: string;
    /**
     * The charge, as a two-colour bar pair. Ignored when {@link BurgeeBrand.charge}
     * is given — that is the escape hatch for a CLI bringing its own glyph.
     */
    mark: BurgeeColors;
    /**
     * Your own charge instead of the bars: SVG markup drawn in a 0 0 100 100 box,
     * which burgee places and scales for you. Everything else — the swallowtail,
     * the reversed field, the sizes — still comes from this one declaration.
     */
    charge?: string;
    /**
     * Your own silhouette instead of the swallowtail: SVG path data in the same
     * `0 0 100 100` box, filled with the field and carrying the charge exactly as
     * the flag does. For a sibling brand whose name is not a flag — a roundel is
     * rings, a parrot is a parrot — the shape is the whole point, and drawing it
     * here keeps every other projection (favicon, lockup, OG, cover) intact.
     */
    shape?: string;
    /**
     * A sheen: a soft highlight laid across the field, `0` to `1`, where the
     * number is how bright its brightest point is. Depth, not decoration — a flat
     * gradient reads as printed ink, and one light source makes the same shape
     * read as an object with a front.
     */
    sheen?: number;
    /**
     * A bevel: how strongly the mark's own edge catches the light, `0` to `1`.
     */
    bevel?: number;
    /**
     * Markings: SVG markup in the same `0 0 100 100` box as {@link BurgeeBrand.shape},
     * drawn over the field and under the charge.
     */
    markings?: string;
    /**
     * The field, as gradient stops along {@link FIELD_AXIS}. One stop is a flat
     * field. Keep a dark stop under the charge or the mark will not read.
     */
    field: readonly FieldStop[];
    /**
     * The outline, outermost band first.
     */
    bordure?: Bordure | readonly Bordure[];
}
```

### BurgeeColors

```ts
interface BurgeeColors {
    /** Leading bar, hoist side. */
    lead: string;
    /** Following bar, fly side. */
    follow: string;
}
```

### CardOptions

```ts
interface CardOptions {
    width?: number;
    height?: number;
    /** Large line. Defaults to the brand name. */
    title?: string;
    /** Small line under it; wraps. */
    subtitle?: string;
    theme?: 'light' | 'dark';
    background?: string;
    foreground?: string;
    muted?: string;
}
```

### FieldStop

One gradient stop: how far along the axis, and what colour.

```ts
interface FieldStop {
    offset: number;
    color: string;
}
```

## Types

### Point

A point in the mark space.

```ts
type Point = readonly [number, number];
```

---

# burgee/cli

> Every export of burgee/cli, with its signature and doc comment: brandCommand, devCommand, migrateCommand, pluginCheckCommand, skillCommand, initCommand and 1 more.

Source: https://burgee.interlace.tools/docs/api/cli

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

```ts
import { brandCommand, devCommand, migrateCommand, … } from 'burgee/cli';
```

## Constants

### brandCommand

```ts
const brandCommand: import("./execute.js").Command<{
    readonly lead: {
        readonly type: "string";
        readonly required: true;
        readonly description: "leading colour, hex. Your primary; it leads the charge upper-left";
    };
    readonly follow: {
        readonly type: "string";
        readonly required: true;
        readonly description: "following colour, hex. Your secondary; it follows lower-right";
    };
    readonly name: {
        readonly type: "string";
        readonly description: "brand name, used as the accessible label and card title";
    };
    readonly ground: {
        readonly type: "string";
        readonly default: "#0a0a0a";
        readonly description: "the field’s dark midpoint, which is what keeps the charge legible";
    };
    readonly charge: {
        readonly type: "string";
        readonly description: "path to an SVG whose contents replace the bars, drawn in a 0 0 100 100 box";
    };
    readonly bordure: {
        readonly type: "string";
        readonly description: "outline colour, hex. Omit for no outline";
    };
    readonly bordureWidth: {
        readonly type: "string";
        readonly default: "1.5";
        readonly description: "outline width";
    };
    readonly tagline: {
        readonly type: "string";
        readonly description: "one line under the name on the card and cover";
    };
    readonly out: {
        readonly type: "string";
        readonly description: "directory to write into. Omit to print the flag only";
    };
    readonly on: {
        readonly type: "string";
        readonly description: "page colour(s) the flag will fly on, comma separated. Checked for contrast";
    };
    readonly allowLowContrast: {
        readonly type: "boolean";
        readonly description: "emit anyway when a contrast check fails. Says so in the output";
    };
}, import("./manifest.js").CommandOutput, readonly []>;
```

### devCommand

`burgee dev <entry>` — watch the entry, reload it on change, serve it as MCP on stdio
and print every surface on each save (dev-loop). Loaded only when asked for, so the
CLI's own weight and the framework's stay what they were (W4).

```ts
const devCommand: import("./execute.js").Command<{
    readonly noWatch: {
        readonly type: "boolean";
        readonly description: "load once and serve; do not watch for changes";
    };
}, import("./manifest.js").CommandOutput, readonly [{
    readonly name: "entry";
    readonly description: "the module that exports the program, as program or as its default export";
    readonly required: true;
}]>;
```

### initCommand

`burgee init [dir]` — a first CLI in one command (first-cli R1–R5): the README quick start as
`cli.mjs` and the `package.json` that runs it, and nothing else. Loaded on this path only, like
`migrate` and `skill`, so neither `import 'burgee'` nor a user's bundle carries it.

```ts
const initCommand: import("./execute.js").Command<{
    readonly install: {
        readonly type: "boolean";
        readonly description: "run the install with the package manager this ran under";
    };
    readonly force: {
        readonly type: "boolean";
        readonly description: "overwrite cli.mjs and package.json when they are already there";
    };
}, import("./manifest.js").CommandOutput, readonly [{
    readonly name: "dir";
    readonly description: "the directory to write into. Defaults to the current directory";
    readonly required: false;
}]>;
```

### migrateCommand

`burgee migrate [dir]` — rewrite a commander or yargs project's imports to burgee's
drop-in front-ends and report what changed, with the numbers that say why it was safe.

```ts
const migrateCommand: import("./execute.js").Command<{
    readonly dryRun: {
        readonly type: "boolean";
        readonly description: "scan and report; write nothing";
    };
    readonly force: {
        readonly type: "boolean";
        readonly description: "migrate even though the git tree has uncommitted changes";
    };
    readonly only: {
        readonly type: "string";
        readonly multiple: true;
        readonly placeholder: "lib,…";
        readonly description: "rewrite only these incumbents, by package name, declared or not";
    };
    readonly skip: {
        readonly type: "string";
        readonly multiple: true;
        readonly placeholder: "lib,…";
        readonly description: "leave these incumbents alone, by package name";
    };
}, import("./manifest.js").CommandOutput, readonly [{
    readonly name: "dir";
    readonly description: "the project to migrate. Defaults to the current directory";
    readonly required: false;
}]>;
```

### pluginCheckCommand

`burgee check <plugin-file>` — the feedback loop PRINCIPLES 7 asks every extension surface
for, and the one burgee did not have. See `check.ts`: this one returns its report as data, so
`--json` is the form an agent that just wrote a plugin reads.

```ts
const pluginCheckCommand: import("./execute.js").Command<import("./execute.js").OptionSpecs, import("./manifest.js").CommandOutput, readonly [{
    readonly name: "file";
    readonly description: "the plugin module to check";
}]>;
```

### program

```ts
const program: import("./manifest.js").Manifest;
```

### skillCommand

`burgee skill <entry> [--out <dir>] [--check]` — the program's Agent Skill (`SKILL.md`) and its
`AGENTS.md`, projected from its declaration and written beside its binary (agent-skill R3).
`--check` writes nothing and exits 1 when the files there differ from the projection, for an
author's own CI. Loaded on this path only, like `dev` and `migrate`.

```ts
const skillCommand: import("./execute.js").Command<{
    readonly out: {
        readonly type: "string";
        readonly placeholder: "dir";
        readonly description: "directory to write into. Defaults to the directory of the bin in the entry's package.json";
    };
    readonly check: {
        readonly type: "boolean";
        readonly description: "write nothing; exit 1 when the files there differ from the projection";
    };
}, import("./manifest.js").CommandOutput, readonly [{
    readonly name: "entry";
    readonly description: "the module that exports the program, as program or as its default export";
    readonly required: true;
}]>;
```

---

# burgee/commander

> burgee/commander is a drop-in for commander: the same API, documented by commander itself. Every name it exports, and where its reference lives.

Source: https://burgee.interlace.tools/docs/api/commander

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts and burgee/src/compat.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

`burgee/commander` is a drop-in for `commander`, graded by the incumbent's own test suite. Its API is the incumbent's, so its reference is the incumbent's own documentation.

- **Reference:** [commander 15.0.0](https://www.npmjs.com/package/commander/v/15.0.0), the release that suite is run at.
- **How closely it matches:** [Compatibility](/docs/compatibility), that suite's result in CI, with every case left out of the gate and the reason.
- **Switching:** [Switching from commander](/docs/vs/commander).
- **Moving a program over:** [`burgee migrate`](/docs/migrate) rewrites `'commander'` to `'burgee/commander'` across a project.

## Exports

Every name `burgee/commander` exports, as the built declarations state them. Signatures and behaviour are commander's.

| Export | Kind |
| :-- | :-- |
| `humanReadableArgName` | function |
| `useColor` | function |
| `Argument` | class |
| `Command` | class |
| `CommanderError` | class |
| `DualOptions` | class |
| `Help` | class |
| `InvalidArgumentError` | class |
| `InvalidOptionArgumentError` | class |
| `Option` | class |
| `createArgument` | const |
| `createCommand` | const |
| `createOption` | const |
| `program` | const |
| `BurgeeParseOptions` | interface |
| `CommandOptions` | interface |
| `ErrorOptions` | interface |
| `ExecutableCommandOptions` | interface |
| `HelpContext` | interface |
| `OutputContext` | interface |
| `ParseOptions` | interface |
| `ParseOptionsResult` | interface |
| `AddHelpTextContext` | type |
| `AddHelpTextPosition` | type |
| `HelpConfiguration` | type |
| `HookEvent` | type |
| `HookListener` | type |
| `OptionValues` | type |
| `OptionValueSource` | type |
| `OutputConfiguration` | type |

---

# burgee/commander/extra-typings

> burgee/commander/extra-typings is a drop-in for @commander-js/extra-typings: the same API, documented by @commander-js/extra-typings itself. Every name it exports, and where its reference lives.

Source: https://burgee.interlace.tools/docs/api/commander/extra-typings

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts and burgee/src/compat.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

`burgee/commander/extra-typings` is a drop-in for `@commander-js/extra-typings`, graded by the incumbent's own test suite. Its API is the incumbent's, so its reference is the incumbent's own documentation.

- **Reference:** [@commander-js/extra-typings 15.0.0](https://www.npmjs.com/package/@commander-js/extra-typings/v/15.0.0), the release that suite is run at.
- **How closely it matches:** [Compatibility](/docs/compatibility), that suite's result in CI, with every case left out of the gate and the reason.
- **Moving a program over:** [`burgee migrate`](/docs/migrate) rewrites `'@commander-js/extra-typings'` to `'burgee/commander/extra-typings'` across a project.

## Exports

Every name `burgee/commander/extra-typings` exports, as the built declarations state them. Signatures and behaviour are @commander-js/extra-typings's.

| Export | Kind |
| :-- | :-- |
| `createArgument` | function |
| `createCommand` | function |
| `createOption` | function |
| `humanReadableArgName` | function |
| `useColor` | function |
| `Argument` | class |
| `Command` | class |
| `CommanderError` | class |
| `DualOptions` | class |
| `Help` | class |
| `InvalidArgumentError` | class |
| `Option` | class |
| `InvalidOptionArgumentError` | const |
| `program` | const |
| `AddHelpTextContext` | interface |
| `BurgeeParseOptions` | interface |
| `CommandOptions` | interface |
| `ErrorOptions` | interface |
| `ExecutableCommandOptions` | interface |
| `HelpContext` | interface |
| `OutputConfiguration` | interface |
| `OutputContext` | interface |
| `ParseOptions` | interface |
| `ParseOptionsResult` | interface |
| `AddHelpTextPosition` | type |
| `CommandUnknownOpts` | type |
| `HelpConfiguration` | type |
| `HookEvent` | type |
| `HookListener` | type |
| `InferArgument` | type |
| `InferArguments` | type |
| `InferCommandArguments` | type |
| `InferOptions` | type |
| `OptionValues` | type |
| `OptionValueSource` | type |

---

# burgee/commander/v14

> Every export of burgee/commander/v14, with its signature and doc comment: Command, program, createCommand, Argument, humanReadableArgName, useColor and 8 more, plus 16 types.

Source: https://burgee.interlace.tools/docs/api/commander/v14

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

`burgee/commander/v14` — `burgee/commander` for a program on commander 14, the entry
`burgee migrate` writes for one (`previous-majors` R1, R6). The one difference commander
14.0.3's own suite measures: its excess-arguments message stops at the count, where 15
names the surplus arguments. Kept out of `command.ts`, so a 15 program bundles none of it.

```ts
import { Command, program, createCommand, … } from 'burgee/commander/v14';
```

## Functions

### humanReadableArgName

`<name>` / `[name]` / `<name...>` for usage strings.

```ts
function humanReadableArgName(arg: Argument): string;
```

| Parameter | Type |
| :-- | :-- |
| `arg` | `Argument` |

**Returns** `string`

### useColor

The common colour conventions: NO_COLOR and FORCE_COLOR=0/false disable, FORCE_COLOR
and CLICOLOR_FORCE enable, otherwise undecided (the stream's TTY-ness decides).

```ts
function useColor(): boolean | undefined;
```

**Returns** `boolean \| undefined`

## Classes

### Argument

```ts
class Argument {
    description: string;
    variadic: boolean;
    parseArg: ParseArg | undefined;
    defaultValue: unknown;
    defaultValueDescription: string | undefined;
    argChoices: string[] | undefined;
    required: boolean;
    _name: string;
    /** `<required>`, `[optional]`, bare = required; a trailing `...` makes it variadic. */
    constructor(name: string, description?: string);
    name(): string;
    _collectValue(value: unknown, previous: unknown): unknown[];
    default(value: unknown, description?: string): this;
    argParser(fn?: ParseArg): this;
    choices(values: readonly string[]): this;
    argRequired(): this;
    argOptional(): this;
}
```

### Command

```ts
class Command extends Current {
    createCommand(name?: string): Command;
    _excessArguments(args: string[]): void;
}
```

### CommanderError

commander's error classes, byte-for-byte in shape: `code`, `exitCode`, `nestedError`.

```ts
class CommanderError extends Error {
    code: string;
    exitCode: number;
    nestedError: unknown;
    constructor(exitCode: number, code: string, message?: string);
}
```

### DualOptions

`--build` and `--no-build` share one value. This works out which of the pair a
value (probably) came from, so implied values are only applied for the right one.

```ts
class DualOptions {
    positiveOptions: Map<string, Option>;
    negativeOptions: Map<string, Option>;
    dualOptions: Set<string>;
    constructor(options: Option[]);
    valueFromOption(value: unknown, option: Option): boolean;
}
```

### Help

Methods are static in style so a subclass, or plain functions via `configureHelp`, can override them.

```ts
class Help {
    helpWidth: number | undefined;
    minWidthToWrap: number;
    sortSubcommands: boolean;
    sortOptions: boolean;
    showGlobalOptions: boolean;
    /** Called after `configureHelp` overrides are applied and just before `formatHelp`. */
    prepareContext(contextOptions: HelpContext): void;
    visibleCommands(cmd: Command): Command[];
    compareOptions(a: Option, b: Option): number;
    visibleOptions(cmd: Command): Option[];
    visibleGlobalOptions(cmd: Command): Option[];
    visibleArguments(cmd: Command): Argument[];
    subcommandTerm(cmd: Command): string;
    optionTerm(option: Option): string;
    argumentTerm(argument: Argument): string;
    longestSubcommandTermLength(cmd: Command, helper: Help): number;
    longestOptionTermLength(cmd: Command, helper: Help): number;
    longestGlobalOptionTermLength(cmd: Command, helper: Help): number;
    longestArgumentTermLength(cmd: Command, helper: Help): number;
    commandUsage(cmd: Command): string;
    commandDescription(cmd: Command): string;
    /** Summary, falling back to description for backwards compatibility. */
    subcommandDescription(cmd: Command): string;
    optionDescription(option: Option): string;
    argumentDescription(argument: Argument): string;
    formatItemList(heading: string, items: string[], helper: Help): string[];
    /** Groups in order of first appearance among all items; members in order of the visible items. */
    groupItems<T>(unsortedItems: T[], visibleItems: T[], getGroup: (item: T) => string): Map<string, T[]>;
    formatHelp(cmd: Command, helper: Help): string;
    /** Width ignoring ANSI escapes, for padding and wrapping. */
    displayWidth(str: string): number;
    styleTitle(str: string): string;
    styleUsage(str: string): string;
    styleCommandDescription(str: string): string;
    styleOptionDescription(str: string): string;
    styleSubcommandDescription(str: string): string;
    styleArgumentDescription(str: string): string;
    styleDescriptionText(str: string): string;
    styleOptionTerm(str: string): string;
    styleSubcommandTerm(str: string): string;
    styleArgumentTerm(str: string): string;
    styleOptionText(str: string): string;
    styleArgumentText(str: string): string;
    styleSubcommandText(str: string): string;
    styleCommandText(str: string): string;
    padWidth(cmd: Command, helper: Help): number;
    /** Manually wrapped text: a line break followed by whitespace. */
    preformatted(str: string): boolean;
    /**
     * Pad the term and wrap the description, indenting the following lines:
     *   TTT  DDD DDDD
     *        DD DDD
     */
    formatItem(term: string, termWidth: number, description: string, helper: Help): string;
    /** Wrap at whitespace, preserving existing line breaks; skipped below `minWidthToWrap`. */
    boxWrap(str: string, width: number): string;
}
```

### InvalidArgumentError

```ts
class InvalidArgumentError extends CommanderError {
    constructor(message?: string);
}
```

### InvalidOptionArgumentError

```ts
class InvalidArgumentError extends CommanderError {
    constructor(message?: string);
}
```

### Option

```ts
class Option {
    flags: string;
    description: string;
    required: boolean;
    optional: boolean;
    variadic: boolean;
    mandatory: boolean;
    short: string | undefined;
    long: string | undefined;
    negate: boolean;
    defaultValue: unknown;
    defaultValueDescription: string | undefined;
    presetArg: unknown;
    envVar: string | undefined;
    parseArg: ParseArg | undefined;
    hidden: boolean;
    argChoices: string[] | undefined;
    conflictsWith: string[];
    implied: Record<string, unknown> | undefined;
    helpGroupHeading: string | undefined;
    constructor(flags: string, description?: string);
    default(value: unknown, description?: string): this;
    /** Value used when the option appears without an option-argument. `parseArg` still runs. */
    preset(arg: unknown): this;
    conflicts(names: string | string[]): this;
    /** Values implied for other options when this one is set and they are not. `parseArg` does not run on them. */
    implies(impliedOptionValues: string | Record<string, unknown>): this;
    env(name: string): this;
    argParser(fn?: ParseArg): this;
    makeOptionMandatory(mandatory?: boolean): this;
    hideHelp(hide?: boolean): this;
    _collectValue(value: unknown, previous: unknown): unknown[];
    choices(values: readonly string[]): this;
    name(): string;
    /** camelCase key used on the options object; `--no-foo` shares `foo` with `--foo`. */
    attributeName(): string;
    helpGroup(heading: string): this;
    is(arg: string): boolean;
    /** Options are one of boolean, negated, required-argument or optional-argument. */
    isBoolean(): boolean;
}
```

## Constants

### createArgument

```ts
const createArgument: (name: string, description?: string) => Argument;
```

### createCommand

```ts
const createCommand: (name?: string) => Command;
```

### createOption

```ts
const createOption: (flags: string, description?: string) => Option;
```

### program

```ts
const program: Command;
```

## Interfaces

### BurgeeParseOptions

burgee's additions: inject the streams and the exit, and get E1 exit codes back (T1).

```ts
interface BurgeeParseOptions extends ParseOptions {
    stdout?: Writer;
    stderr?: Writer;
    exit?: (code: number) => void;
}
```

### CommandOptions

```ts
interface CommandOptions {
    hidden?: boolean;
    isDefault?: boolean;
    /** @deprecated since v7, replaced by hidden */
    noHelp?: boolean;
}
```

### ErrorOptions

```ts
interface ErrorOptions {
    code?: string;
    exitCode?: number;
}
```

### ExecutableCommandOptions

```ts
interface ExecutableCommandOptions extends CommandOptions {
    executableFile?: string;
}
```

### HelpContext

```ts
interface HelpContext {
    error?: boolean;
    helpWidth?: number;
    outputHasColors?: boolean;
}
```

### OutputContext

```ts
interface OutputContext {
    error?: boolean;
}
```

### ParseOptions

```ts
interface ParseOptions {
    from?: 'node' | 'electron' | 'user' | 'eval';
}
```

### ParseOptionsResult

`.parseOptions()`'s split of an argv into operands and unknown options.

```ts
interface ParseOptionsResult {
    operands: string[];
    unknown: string[];
}
```

## Types

### AddHelpTextContext

```ts
type AddHelpTextContext = {
    error: boolean;
    command: Command;
};
```

### AddHelpTextPosition

```ts
type AddHelpTextPosition = 'beforeAll' | 'before' | 'after' | 'afterAll';
```

### HelpConfiguration

What `.configureHelp()` takes: any subset of `Help`'s methods and settings.

```ts
type HelpConfiguration = Partial<Help>;
```

### HookEvent

```ts
type HookEvent = 'preSubcommand' | 'preAction' | 'postAction';
```

### HookListener

```ts
type HookListener = (thisCommand: Command, actionCommand: Command) => void | Promise<void>;
```

### OptionValues

commander's option-value types, as `typings/index.d.ts` declares them. `any` is
commander's choice and the point: `program.opts().port` is usable without a cast, and
`opts<T>()` narrows it — a program written against commander's types relies on both;
`unknown` here breaks every `opts().x` such a program reads.

```ts
type OptionValues = Record<string, any>;
```

### OptionValueSource

Where an option's value came from. A string, so an author can define their own; the known ones autocomplete.

```ts
type OptionValueSource = 'default' | 'config' | 'env' | 'cli' | 'implied' | (string & Record<never, never>) | undefined;
```

### OutputConfiguration

commander's `OutputConfiguration`: every member optional, because `.configureOutput()`
takes any subset of them and a typed program annotates exactly that subset. What
`.configureOutput()` hands back is the resolved, complete one.

```ts
type OutputConfiguration = Partial<ResolvedOutputConfiguration>;
```

---

# burgee/completions

> Every export of burgee/completions, with its signature and doc comment: completionTree, renderFigSpec, renderCompletion, SHELLS, plus 1 type.

Source: https://burgee.interlace.tools/docs/api/completions

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

Completions, generated statically from the manifest (D2): bash, zsh, fish and
PowerShell scripts that never run Node on TAB (D3), plus a Fig spec from the same walk
(D5). Every script is deterministic for a manifest, so a snapshot pins it and the shell
itself exercises it in CI (D4).

```ts
import { completionTree, renderFigSpec, renderCompletion, … } from 'burgee/completions';
```

## Functions

### completionTree

The tree the templates walk; the root's own name is the program name.

```ts
function completionTree(manifest: Manifest): {
    program: string;
    root: Node;
};
```

| Parameter | Type |
| :-- | :-- |
| `manifest` | `Manifest` |

**Returns** `{ program: string; root: Node; }`

### renderCompletion

```ts
function renderCompletion(manifest: Manifest, shell: Shell): string;
```

| Parameter | Type |
| :-- | :-- |
| `manifest` | `Manifest` |
| `shell` | `Shell` |

**Returns** `string`

### renderFigSpec

A Fig spec (`Fig.Spec`) from the same walk (D5): one entry per node, children attached by path.

```ts
function renderFigSpec(manifest: Manifest): FigSubcommand;
```

| Parameter | Type |
| :-- | :-- |
| `manifest` | `Manifest` |

**Returns** `FigSubcommand`

## Constants

### SHELLS

```ts
const SHELLS: readonly Shell[];
```

## Types

### Shell

```ts
type Shell = 'bash' | 'zsh' | 'fish' | 'pwsh';
```

---

# burgee/config

> Every export of burgee/config, with its signature and doc comment: ConfigError, envName, resolve, screaming, explain, plus 5 types.

Source: https://burgee.interlace.tools/docs/api/config

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

`burgee/config` — the configuration layer, by itself.

```ts
import { ConfigError, envName, resolve, … } from 'burgee/config';
```

## Functions

### envName

```ts
function envName(name: string, spec: OptionSpec, prefix: string | undefined): string | undefined;
```

| Parameter | Type |
| :-- | :-- |
| `name` | `string` |
| `spec` | `OptionSpec` |
| `prefix` | `string \| undefined` |

**Returns** `string \| undefined`

### explain

The rendered form: what `--explain` prints.

```ts
function explain(name: string, resolution: Resolution): string;
```

| Parameter | Type |
| :-- | :-- |
| `name` | `string` |
| `resolution` | `Resolution` |

**Returns** `string`

### resolve

Every declared option, resolved through the layers; a missing required one is left undefined for the caller to report.

```ts
function resolve(specs: Record<string, OptionSpec>, layers: Layers): Resolution;
```

| Parameter | Type |
| :-- | :-- |
| `specs` | `Record<string, OptionSpec>` |
| `layers` | `Layers` |

**Returns** `Resolution`

### screaming

`region` → `REGION`, `dryRun` → `DRY_RUN`, `log-level` → `LOG_LEVEL` (yargs #2005: never camel-cased back).

```ts
function screaming(name: string): string;
```

| Parameter | Type |
| :-- | :-- |
| `name` | `string` |

**Returns** `string`

## Classes

### ConfigError

A value that cannot be used as configured: exit CONFIG (3), never a stack (E1, E3).

```ts
class ConfigError extends Error {
    readonly hint?: string | undefined;
    constructor(message: string, hint?: string | undefined);
}
```

## Interfaces

### Candidate

```ts
interface Candidate {
    source: Source;
    location: string;
    /** `undefined` when the layer had nothing for this option. */
    value: unknown;
    /** The line in `location` that set it, when the layer knows (R3). */
    line?: number;
}
```

### Layers

```ts
interface Layers {
    /** What the user typed: only options present on the command line. */
    flags: Record<string, unknown>;
    env: Record<string, string | undefined>;
    /** With a prefix, an option without `env:` reads `PREFIX_OPTION_NAME` (R2). */
    envPrefix?: string;
    config?: Layer;
    /** The `package.json` field named after the program, when present. */
    pkg?: Layer;
    /** Plugin-contributed sources, already read — see `seniority/plugin`'s `sources()`. */
    sources?: readonly SourceLayer[];
}
```

### Provenance

```ts
interface Provenance {
    source: Source;
    /** The env name, the config file, or `package.json` — where a person would look. */
    location?: string;
    /** The line within `location`, when the layer recorded one (R3). A file source may; an env name cannot. */
    line?: number;
}
```

### Resolution

```ts
interface Resolution {
    values: Record<string, unknown>;
    provenance: Record<string, Provenance>;
    candidates: Record<string, Candidate[]>;
}
```

## Types

### Source

An **open** union (R13, PLAN D5). A plugin's source is a `Source` seniority has never
heard of; `(string & {})` keeps the five as completions while admitting the rest, so the
`sources` host of PLAN 1.3 is the additive change it reads as rather than a type break.

```ts
type Source = BuiltinSource | (string & {});
```

---

# burgee/contrast

> Every export of burgee/contrast, with its signature and doc comment: mix, ratio, check, report, fieldColorAt, auditBurgee and 3 more, plus 2 types.

Source: https://burgee.interlace.tools/docs/api/contrast

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

Contrast, as a thing the package checks rather than a thing someone remembers.

```ts
import { mix, ratio, check, … } from 'burgee/contrast';
```

## Functions

### auditBurgee

Every contrast relationship a burgee has to survive.

```ts
function auditBurgee(brand: AuditInput, grounds?: readonly string[]): ContrastFinding[];
```

| Parameter | Type |
| :-- | :-- |
| `brand` | `AuditInput` |
| `grounds` (optional) | `readonly string[]` |

**Returns** `ContrastFinding[]`

### check

```ts
function check(what: string, a: string, b: string, required?: 3): ContrastFinding;
```

| Parameter | Type |
| :-- | :-- |
| `what` | `string` |
| `a` | `string` |
| `b` | `string` |
| `required` (optional) | `3` |

**Returns** `ContrastFinding`

### contrast

The WCAG contrast ratio between two colours. Order does not matter.

```ts
function contrast(a: string, b: string): number;
```

| Parameter | Type |
| :-- | :-- |
| `a` | `string` |
| `b` | `string` |

**Returns** `number`

### fieldColorAt

The field colour at a point along the gradient axis, for stops given in order.

```ts
function fieldColorAt(stops: ReadonlyArray<{
    offset: number;
    color: string;
}>, at: number): string;
```

| Parameter | Type |
| :-- | :-- |
| `stops` | `ReadonlyArray<{ offset: number; color: string; }>` |
| `at` | `number` |

**Returns** `string`

### luminance

WCAG relative luminance.

```ts
function luminance(hex: string): number;
```

| Parameter | Type |
| :-- | :-- |
| `hex` | `string` |

**Returns** `number`

### mix

Mix two colours in sRGB. Enough for reading a gradient stop, not for colour science.

```ts
function mix(a: string, b: string, t: number): string;
```

| Parameter | Type |
| :-- | :-- |
| `a` | `string` |
| `b` | `string` |
| `t` | `number` |

**Returns** `string`

### ratio

Round to 2dp for reporting, without pretending to more precision than that — roundel's `round2`.

```ts
function ratio(a: string, b: string): number;
```

| Parameter | Type |
| :-- | :-- |
| `a` | `string` |
| `b` | `string` |

**Returns** `number`

### report

One line per finding, aligned, for a terminal or a failing test.

```ts
function report(findings: readonly ContrastFinding[]): string;
```

| Parameter | Type |
| :-- | :-- |
| `findings` | `readonly ContrastFinding[]` |

**Returns** `string`

## Constants

### AA

The floors WCAG 2.2 sets, as ratios.

```ts
const AA: {
    /** Body text against its background. */
    readonly TEXT: 4.5;
    /** Large text, UI components, and meaningful parts of a graphic. */
    readonly GRAPHIC: 3;
};
```

## Interfaces

### AuditInput

```ts
interface AuditInput {
    mark: {
        lead: string;
        follow: string;
    };
    field: ReadonlyArray<{
        offset: number;
        color: string;
    }>;
    bordure?: {
        color: string;
        width: number;
    } | ReadonlyArray<{
        color: string;
        width: number;
    }>;
}
```

### ContrastFinding

```ts
interface ContrastFinding {
    /** What was compared, in the words someone fixing it would use. */
    what: string;
    a: string;
    b: string;
    ratio: number;
    required: number;
    passes: boolean;
}
```

---

# burgee/help

> Every export of burgee/help, with its signature and doc comment: renderHelp, plus 3 types.

Source: https://burgee.interlace.tools/docs/api/help

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

`burgee/help` — the help renderer, by itself. See `index.ts` for why it is not in the barrel.

```ts
import { renderHelp } from 'burgee/help';
```

## Functions

### renderHelp

Render help for one node — a runnable command, a group, or both — as text.
Deterministic for a given node and width; a snapshot suite pins it. With `color`
off — the default — a theme changes nothing; with it on, only ANSI is added.

```ts
function renderHelp(manifest: Manifest, node: CommandNode, opts?: HelpOptions & {
    format?: 'text';
}): string;

function renderHelp(manifest: Manifest, node: CommandNode, opts: HelpOptions & {
    format: 'markdown';
}): Promise<string>;
```

| Parameter | Type |
| :-- | :-- |
| `manifest` | `Manifest` |
| `node` | `CommandNode` |
| `opts` (optional) | `HelpOptions & { format?: 'text'; }` |

**Returns** `string`

## Interfaces

### HelpOptions

```ts
interface HelpOptions {
    /** Columns available; 100 when unknown, never `process.stdout` directly (H3). */
    width?: number;
    /** Show type hints such as `[string]`; off by default (H6). */
    verbose?: boolean;
    /** Apply colour (R7). Off by default: the renderer is pure, so the TTY and NO_COLOR decision stays with the caller. */
    color?: boolean;
    /**
     * Replaces the default styling token by token; read only when `color` is on. See
     * `HelpTheme` for the lines it leaves plain: the `Usage:` command name and `$ example`.
     */
    theme?: HelpTheme;
    /**
     * The commands to list, in place of the node's visible children: each by its path from the
     * node, with what it takes (`config get <key>`), under the heading of the child it is reached
     * through. The engine passes every command that runs when they fit (`listed` in `usage.ts`).
     */
    commands?: readonly CommandNode[];
    /**
     * More rows for `Global options:`, after `--json`, `--help` and `--schema`: the global flags
     * the engine parses for this command (`--color`, `--quiet`, `--timeout`; agent-lint-conformance
     * R1–R3), passed in by the engine like `commands`, so this renderer carries none of their words.
     */
    globals?: readonly {
        term: string;
        text: string;
    }[];
    /**
     * The run's language (`localised-human-surfaces` R1): every heading, row text and the root's
     * line for agents are passed through it once laid out in English (the node's own description
     * arrives already in the run's language, R5). The engine hands in a pack's translator; absent,
     * it is the identity, and help is byte-for-byte what it was.
     */
    say?: (english: string) => string;
    /**
     * Words the engine adds to the root's line for agents: `AGENTS.md`, when one sits beside the
     * binary (agent-skill R4). Passed in like `commands`, so this renderer looks for no file.
     */
    forAgents?: string;
}
```

## Types

### HelpTheme

Per-token styling for help (R7). A user who has `roundel` passes its tokens; a user
who does not gets the defaults. Help reads `heading`, `command`, `flag` and `value`;
the others are accepted so one theme object serves the whole output stack.

```ts
type HelpTheme = Partial<Record<HelpToken, (s: string) => string>>;
```

### HelpToken

The token names of `roundel`'s R3, typed structurally: help never imports the tokens (U13).

```ts
type HelpToken = 'error' | 'warn' | 'ok' | 'hint' | 'muted' | 'command' | 'flag' | 'value' | 'heading';
```

---

# burgee

> Every export of burgee, with its signature and doc comment: defineError, ExitCode, isExitCode, ExitCodeValue, defineCommand, defineProgram and 14 more, plus 59 types.

Source: https://burgee.interlace.tools/docs/api

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

burgee — a command declares itself once; every surface is that declaration
read by a different reader.

```ts
import { defineError, ExitCode, isExitCode, … } from 'burgee';
```

## Functions

### camel

`--dry-run` on the command line reaches the handler as `dryRun`.

```ts
function camel(flag: string): string;
```

| Parameter | Type |
| :-- | :-- |
| `flag` | `string` |

**Returns** `string`

### checkCommand

The whole door: {@link checkDefinition} — which carries V5's reserved names — and
{@link checkEffects }.

```ts
function checkCommand(name: string, declared: Declared): void;
```

| Parameter | Type |
| :-- | :-- |
| `name` | `string` |
| `declared` | `Declared` |

**Returns** `void`

### checkDefinition

What must be true of a declaration before anything runs (yargs #1198, #887, #1679):
a known type, one short alias per command, no two keys that meet on the command line, and
none of V5's reserved surfaces.

```ts
function checkDefinition(name: string, options: Record<string, OptionSpec>): void;
```

| Parameter | Type |
| :-- | :-- |
| `name` | `string` |
| `options` | `Record<string, OptionSpec>` |

**Returns** `void`

### defineCommand

```ts
function defineCommand<const S extends OptionSpecs = OptionSpecs, const O extends CommandOutput = CommandOutput, const A extends readonly DeclaredArgument[] = readonly []>(command: Command<S, O, A>): Command<S, O, A>;
```

| Parameter | Type |
| :-- | :-- |
| `command` | `Command<S, O, A>` |

**Returns** `Command<S, O, A>`

### defineError

```ts
function defineError(definition: ErrorDefinition): DefinedErrorClass;
```

| Parameter | Type |
| :-- | :-- |
| `definition` | `ErrorDefinition` |

**Returns** `DefinedErrorClass`

### defineProgram

A native multi-command program. The manifest it builds is the same one the façades fill.

```ts
function defineProgram(program: Program): Manifest;
```

| Parameter | Type |
| :-- | :-- |
| `program` | `Program` |

**Returns** `Manifest`

### detectAgent

```ts
function detectAgent(env: Record<string, string | undefined>, tty: boolean, probes?: readonly AgentProbe[]): Detection;
```

| Parameter | Type |
| :-- | :-- |
| `env` | `Record<string, string \| undefined>` |
| `tty` | `boolean` |
| `probes` (optional) | `readonly AgentProbe[]` |

**Returns** `Detection`

### execute

```ts
function execute(manifest: Manifest, opts?: RunOptions & {
    root?: string[];
    from?: 'node' | 'user';
}): Promise<void>;
```

| Parameter | Type |
| :-- | :-- |
| `manifest` | `Manifest` |
| `opts` (optional) | `RunOptions & { root?: string[]; from?: 'node' \| 'user'; }` |

**Returns** `Promise<void>`

### kebab

`dryRun` → `dry-run`; a kebab key stays as it is.

```ts
function kebab(name: string): string;
```

| Parameter | Type |
| :-- | :-- |
| `name` | `string` |

**Returns** `string`

### resolveCommand

M6: which command argv names, or null — the same longest-prefix match `execute` uses, over the
declared names. An alias is not read here: `execute` rewrites one to its command's name before it
resolves (`aliases.ts`, facade-projection-fidelity R5), and that chunk is loaded only on a run, so
this function stays synchronous and off the startup path. Pass the canonical words.

```ts
function resolveCommand(manifest: Manifest, argv: readonly string[]): CommandNode | null;
```

| Parameter | Type |
| :-- | :-- |
| `manifest` | `Manifest` |
| `argv` | `readonly string[]` |

**Returns** `CommandNode \| null`

### run

The one-file entry: a single command, or a program from `defineProgram`. Both go
through `execute`, so there is exactly one code path from argv to exit.

```ts
function run<S extends OptionSpecs, A extends readonly DeclaredArgument[] = readonly []>(target: Command<S, CommandOutput, A> | Manifest, opts?: RunOptions): Promise<void>;
```

| Parameter | Type |
| :-- | :-- |
| `target` | `Command<S, CommandOutput, A> \| Manifest` |
| `opts` (optional) | `RunOptions` |

**Returns** `Promise<void>`

### runCommand

M6: run a command programmatically — the harness's own entry, public. The streams are
captured, the exit recorded; env, cwd and the entry can be injected like `execute`'s.

```ts
function runCommand(manifest: Manifest, argv: readonly string[], opts?: Pick<RunOptions, 'env' | 'cwd' | 'entry' | 'stdin' | 'locale'>): Promise<RunResult>;
```

| Parameter | Type |
| :-- | :-- |
| `manifest` | `Manifest` |
| `argv` | `readonly string[]` |
| `opts` (optional) | `Pick<RunOptions, 'env' \| 'cwd' \| 'entry' \| 'stdin' \| 'locale'>` |

**Returns** `Promise<RunResult>`

### sharedOptions

Options declared once and spread into each command that takes them (M4): never global,
so `--schema` stays a tree and each command's help lists them as its own, and the
handler's `options` type carries them like any other. Every copy is tagged
`sharedFrom` with the set's name, so the schema says where it came from.

```ts
function sharedOptions<const T extends OptionSpecs>(name: string, specs: T): T;
```

| Parameter | Type |
| :-- | :-- |
| `name` | `string` |
| `specs` | `T` |

**Returns** `T`

## Classes

### AuthError

E6 — the far side said no. Throw this and the run leaves with `ExitCode.AUTH`.

```ts
class AuthError extends Error {
    readonly hint?: string | undefined;
    readonly fix?: string | undefined;
    constructor(message: string, hint?: string | undefined, fix?: string | undefined);
}
```

### UsageError

A usage problem the caller can fix, carrying the flag that fixes it (E3).

```ts
class UsageError extends Error {
    readonly hint?: string | undefined;
    constructor(message: string, hint?: string | undefined);
}
```

## Constants

### AGENT_PROBES

```ts
const AGENT_PROBES: readonly AgentProbe[];
```

## Interfaces

### ActionRequiredSpec

What a caller must do before the command can continue (N11): synthesised into the envelope.

```ts
interface ActionRequiredSpec {
    /** A short machine-readable reason: `login`, `confirm`, `missing-config` … */
    reason: string;
    message: string;
    /** Runnable commands, each with when to run it; the engine prefixes the program and carries the caller's flags. */
    next?: readonly {
        command: string;
        when: string;
    }[];
    hint?: string;
}
```

### AgentProbe

Agent detection, not just `isTTY` (N12). An agent may well have a terminal; what it
does not have is a person. `FORCE_TTY=1` overrides. `AI_AGENT` is the generic escape
hatch any agent can set.

```ts
interface AgentProbe {
    /** Environment variable whose presence names the agent. */
    variable: string;
    agent: string;
}
```

### ArgumentSpec

A positional, as help documents it (yargs #2012).

```ts
interface ArgumentSpec {
    name: string;
    description?: string;
    required?: boolean;
    variadic?: boolean;
    default?: string;
    /**
     * The values the positional accepts, published as `enum` the way an option's `choices` are
     * (facade-projection-fidelity R3), and enforced: the commander façade while parsing, the
     * engine before the handler (typed-positionals R3). A string type's alone, as on an option.
     */
    choices?: readonly string[];
    /**
     * What the word is (typed-positionals R1, D-20261012-typed-positionals-shape): `ctx.args`
     * carries it as that type, and a word that is not one is a usage error. Absent is `string`.
     * `'file'` is a path, where `-` means standard input — handed to the handler as `ctx.stdin` (S4).
     */
    type?: 'string' | 'number' | 'integer' | 'boolean' | 'file';
    /**
     * completion-context R3 — values computed when TAB lands on this positional, called as an
     * option's completer is. zsh still offers files for a `type: 'file'` argument.
     */
    complete?: Completer;
}
```

### Command

```ts
interface Command<S extends OptionSpecs = OptionSpecs, O extends CommandOutput = CommandOutput, A extends readonly DeclaredArgument[] = readonly []> {
    name: string;
    /** Other words that run this command, `['s']` for `serve`: listed on it in help, `--schema` and completions, never as commands of their own. */
    aliases?: readonly string[];
    /**
     * Runs when argv names no command at this level (default-command R2): `tool`, or `tool --port 1`
     * with only this command's options, and a word as its positional when it declares one and the
     * word is near no command's name. One per level; two siblings that both say so are refused.
     */
    default?: boolean;
    description?: Localised;
    /** Shown in command lists instead of the description. */
    summary?: Localised;
    /** Declared once (S1); the handler's `options` type is derived from it. */
    options?: S;
    /** Positionals in order, each with its `type` and `choices` (typed-positionals R1); the handler reads them as `args`. */
    arguments?: A;
    examples?: DeclaredExample[];
    /** Heading this command is listed under in its parent's help. */
    group?: string;
    epilogue?: string;
    hidden?: boolean;
    /** What replaces this command, e.g. `'deploy'`: shown in help, `--schema` and the warning. `true` alone is refused (D1). */
    deprecated?: boolean | string;
    /**
     * What running it does to the world (N6). Declaring one of the three is what exposes the
     * command as an MCP tool (N2); `'withheld'` declares that it is not offered to agents.
     */
    effects?: DeclaredEffects;
    /** Relationships between options, validated before choices and the handler (S2, S6). */
    relations?: readonly Relation[];
    /**
     * The top-level fields of this command's result (N14). With them, `--json=` lists them
     * without running the handler and `--json=a,b` refuses an unknown field before it runs.
     * Without them `--json=a,b` still selects, checked against the result's own keys.
     */
    fields?: readonly string[];
    /**
     * clispec-conformance R5 — what the result is and how much of it: `--schema` publishes it as
     * `output_kind`, `cardinality` and `stdout_schema`. With a `schema`, `run` must return what it
     * describes; without one, anything.
     */
    output?: O;
    /** Pass positionals past the declared ones to the handler instead of refusing them. */
    allowExcess?: boolean;
    /** Absent on a group that only holds subcommands. `NoInfer`: the spec fixes S, the handler only reads it. */
    run?: (ctx: CommandContext<InferOptions<NoInfer<S>>, InferArgs<NoInfer<A>>>) => Returns<NoInfer<O>>;
    /** The handler's module, imported on dispatch only (M2); everything else about the command is declared here. */
    load?: () => Promise<LazyModule>;
    commands?: AnyCommand[];
}
```

### CommandContext

```ts
interface CommandContext<O, A = Record<string, unknown>> extends Omit<RunContext, 'options' | 'args'> {
    options: O;
    /** The declared positionals by name, typed from the declaration (typed-positionals R2). */
    args: A;
}
```

### CommandNode

```ts
interface CommandNode {
    path: string[];
    /**
     * Other words that name this command where its own last path segment would be typed:
     * commander's `.alias()`, yargs' `['serve', 's']` (facade-projection-fidelity R5). A field on
     * the command, never a second command, so `--schema` and an MCP tool list do not double.
     * The engine reads them in `aliases.ts`; a façade dispatches its own.
     */
    aliases?: readonly string[];
    /** The command that runs when argv names none at its parent's level (default-command R2); one per level. */
    default?: boolean;
    description?: string;
    /** Shown in command lists instead of the description (yargs #1265). */
    summary?: string;
    options: Record<string, OptionSpec>;
    relations?: readonly Relation[];
    arguments?: ArgumentSpec[];
    examples?: Example[];
    /** Heading this command is listed under in its parent's help (yargs #684). */
    group?: string;
    epilogue?: string;
    hidden?: boolean;
    deprecated?: boolean | string;
    /**
     * What running it does to the world, or `'withheld'` (N2, N6). Required on a node that
     * runs — `checkCommand` refuses one that omits it — and optional on the type, because a
     * group carries no `effects` and the host front-ends build nodes that never reach that
     * door: commander and yargs have no notion of effects and their graded suites declare
     * none, so a façade's command is withheld in fact and cannot be made to say so.
     */
    effects?: DeclaredEffects;
    /** The result's top-level fields, as declared (N14); what `--json=` lists. */
    fields?: readonly string[];
    /** What the result is and how much of it (clispec-conformance R5). */
    output?: CommandOutput;
    allowExcess?: boolean;
    run?: (ctx: RunContext) => unknown;
    /**
     * The handler's module, imported on dispatch only (M2): the manifest — help, schema,
     * completions, MCP tool list — is complete from this node without loading it. A node
     * with `load` and no `run` gets a `run` that imports on first call.
     */
    load?: () => Promise<LazyModule>;
    /** Which plugin contributed this, if any. Declared, never diffed (M3). */
    plugin?: string;
}
```

### CommandOutput

clispec-conformance R5 — what a command's result is, declared, so `--schema` can say what
comes back and how much of it before the first call (clispec v0.3's `output_kind`,
`cardinality`, `stdout_schema` and `media_type`).

```ts
interface CommandOutput {
    kind?: 'data' | 'stream' | 'opaque';
    cardinality?: 'single' | 'bounded' | 'unbounded';
    schema?: OutputSchema;
    /** `opaque` only: what the bytes are, such as `text/plain`. */
    mediaType?: string;
}
```

### CompletionContext

completion-context R1 — what a completer is told about the line, beside the partial word.
Only what was typed before the cursor: no env, config or default is read on TAB.

```ts
interface CompletionContext {
    /** The command's path as declared, without the program's own name: `['deploy']`. */
    readonly path: readonly string[];
    /**
     * The options typed before the cursor, coerced the way a run coerces them (numbers, choices,
     * Standard Schema) and keyed camelCase. The line is unfinished, so nothing is required and no
     * relation is checked, and the option whose value is being completed is not here.
     */
    readonly options: Readonly<Record<string, unknown>>;
    /** The positionals typed before the cursor, as typed. */
    readonly positionals: readonly string[];
    /**
     * An option whose value failed coercion, as typed, and not in `options` (R2). A repeatable
     * option is coerced whole, so one bad element puts every value it was given here, joined by its
     * separator (`--level 1 --level x` is `level: '1,x'`).
     */
    readonly raw: Readonly<Record<string, string>>;
}
```

### DefinedErrorClass

An author-defined error class; `exitCode` is the code it leaves with.

```ts
interface DefinedErrorClass {
    new (message: string, options?: DefinedErrorOptions): Error & DefinedErrorOptions;
    readonly exitCode: number;
}
```

### DefinedErrorOptions

What `new` takes: the message, and optionally the E3 `hint` and exact `fix`.

```ts
interface DefinedErrorOptions {
    hint?: string;
    fix?: string;
}
```

### Detection

```ts
interface Detection {
    /** The agent named by the environment, if any; `AI_AGENT`'s own value when it names one. */
    agent?: string;
    /**
     * stdout is a terminal and no agent is named, or `FORCE_TTY=1`: the output side, which help's
     * colour reads. Whether to *ask* is `ctx.interactive`, roundel's rule over stdin and `CI`.
     */
    interactive: boolean;
}
```

### ErrorDefinition

What an author declares.

```ts
interface ErrorDefinition {
    /** The class name, shown as the error's `name`. */
    name: string;
    /** The exit code, 7–125, owned by this class alone. */
    code: number;
    /**
     * clispec-conformance R2 — the word the failure is, snake_case and this class's alone: the
     * envelope's `error.kind` and its row in `--schema`'s `errors`. Without one it is the name in
     * snake case, less a trailing `Error` (`QuotaExceededError` → `quota_exceeded`).
     */
    kind?: string;
    /** Whether running the same command again may succeed; `false` unless said (R2). */
    retryable?: boolean;
    /** What the failure means, for its `errors` row (R2). */
    description?: string;
}
```

### Example

One example: a single copy-pasteable command line, the description below it (H2).

```ts
interface Example {
    command: string;
    description?: string;
}
```

### Hook

```ts
interface Hook {
    filter?: HookFilter;
    /** `parse` may return the argv to use instead; every other stage's return is ignored. */
    handler: (ctx: HookContext) => unknown;
}
```

### LazyModule

What a lazily loaded command module exports: the handler as `run` or as the default export (M2).

```ts
interface LazyModule {
    default?: (ctx: RunContext) => unknown;
    run?: (ctx: RunContext) => unknown;
}
```

### OptionSpec

```ts
interface OptionSpec {
    /** `boolean` never consumes a value (S7); `number` rejects NaN and Infinity (S3). */
    type: 'string' | 'boolean' | 'number';
    /**
     * D3 / D-119 — values computed when a person presses TAB: the generated script calls the
     * program back (`<program> __complete <words before the cursor> <partial>`) for this option
     * and no other. Declaring it is the opt-in; an option without one completes from `choices`, or
     * not at all, and never runs the program.
     */
    complete?: Completer;
    description?: string;
    required?: boolean;
    short?: string;
    default?: string | boolean | number | readonly string[] | readonly number[];
    /** Environment variable consulted when the flag is absent (V2). Read from the injected env, never process.env directly. */
    env?: string;
    /** Allowed values, enforced and shown as `(one of: a, b)` (yargs #1408, #1186). */
    choices?: readonly string[];
    /** Repeatable, and split on `separator` (`,` unless declared): `--tag a --tag b,c` → `['a', 'b', 'c']` (S8). */
    multiple?: boolean;
    separator?: string;
    /**
     * The other options this one requires: `--out --dependsOn force` is a usage error without
     * `--force` (S2). Sugar for a `{ implies: [this, other] }` relation per name, and nothing
     * else — one engine, one order, one error vocabulary.
     */
    dependsOn?: readonly string[];
    /**
     * The other options this one may not be given with (S2): `{ conflicts: [this, other] }` per
     * name. Commander's `.conflicts()`, yargs' `.conflicts()`, Fig's `exclusiveOn`.
     */
    exclusive?: readonly string[];
    /** `number` only. */
    minimum?: number;
    maximum?: number;
    integer?: boolean;
    /** Any Standard Schema, run on the parsed value; its issues become a usage error (S1). */
    schema?: StandardSchemaV1;
    /** The value's name in help: `--id <dataset-id>` (yargs #833). */
    placeholder?: string;
    /** `true` renders `(deprecated)`; a string names the replacement: `(deprecated: use --force)` (yargs #2248). */
    deprecated?: boolean | string;
    hidden?: boolean;
    /**
     * `boolean` only: whether `--no-<name>` is accepted. Every boolean is negatable unless this
     * says `false`. burgee's own parser negates every boolean (see `toParseConfig`); the
     * commander façade sets `false` where commander would refuse the negation, so completions
     * and `--mcp` never offer or send a flag the parser behind them rejects.
     */
    negatable?: boolean;
    /** The shared set this option was copied from (M4); `--schema` carries it, help lists the option like any other. */
    sharedFrom?: string;
}
```

### Program

```ts
interface Program {
    name: string;
    version?: string;
    description?: Localised;
    /** Options read `PREFIX_OPTION_NAME` from the environment unless they name their own variable (V2). */
    envPrefix?: string;
    /** Characters of `--schema` output above which it is summarised (N13); 48,000 by default. */
    schemaBudget?: number;
    /**
     * Opt into config discovery (V6): `--config <path>` > `NAME_CONFIG` > `./name.config.{json,mjs,js,cjs}`
     * > `package.json#name` > the user config directory; `true` uses the program's name.
     */
    config?: boolean | {
        name: string;
    };
    /** Shown under `Examples:` in root help; without them, each top-level command's first example is (agent-lint-conformance R6). */
    examples?: DeclaredExample[];
    /**
     * The credential a non-interactive caller supplies, by the environment variable it sets (agent-lint-conformance
     * R8). Declared, the program's exit-code contract lists `auth` and names the variable in its advice
     * and in an `AuthError`'s default hint; undeclared, the program claims no auth failure at all.
     */
    auth?: {
        env: string;
    };
    commands: AnyCommand[];
}
```

### RunContext

```ts
interface RunContext {
    options: Record<string, unknown>;
    /**
     * The declared positionals by name, typed (typed-positionals R2): a variadic one as an array,
     * an absent optional one as its `default`. `positionals` beside it is the words as typed.
     */
    args: Record<string, unknown>;
    positionals: string[];
    passthrough: string[];
    /**
     * Standard input, present only when a `type: 'file'` argument was given `-` (S4). The
     * positional still reads `-`, so a handler checks it the same way it checks a path.
     */
    stdin?: NodeJS.ReadableStream;
    env: Record<string, string | undefined>;
    /** Exit with an E1 code. Unwinds cleanly: the code is honoured and nothing is printed. */
    exit: (code: number) => never;
    /**
     * A person may be asked and be expected to answer (N12): roundel's `interactive()`, the
     * family's one rule — a terminal on stdin, no `CI`, no detected agent — or `FORCE_TTY=1`.
     */
    interactive: boolean;
    /** The agent the environment names, if any (N12). */
    agent?: string;
    /** Stop and tell the caller what to do instead of blocking on a prompt (N11). */
    actionRequired: (spec: ActionRequiredSpec) => never;
    /**
     * Cleanup that runs on **every** path out of the run (E5): a normal return, `ctx.exit`,
     * Ctrl-C, SIGTERM, a terminal closing, an uncaught throw. Returns the function that
     * unregisters it, for a command that cleaned up on its own.
     */
    onExit: (handler: () => void | Promise<void>, label?: string) => () => void;
    /**
     * agent-lint-conformance R3 — aborts when the `--timeout` the caller set has passed, with the
     * timeout error as its `reason`. Hand it to `fetch`, a child process or anything else that
     * takes a signal, so the work stops when the run does. A run without `--timeout` still has one;
     * it never aborts.
     */
    signal: AbortSignal;
    /**
     * mcp-current R5 — report how far the command has got: `done` of `total` units, with an
     * optional `message`. Inside an `--mcp` tool call whose client sent a `progressToken`, each
     * call is a `notifications/progress`; everywhere else it does nothing, so call it
     * unconditionally. `flagstaff/progress` reports through it on its own inside such a call.
     */
    progress: (done: number, total?: number, message?: string) => void;
    /** agent-lint-conformance R2 — the caller passed `--quiet`: draw no progress and print no hints. Data and errors still print. */
    quiet: boolean;
    /**
     * The output policy's runtime for this run (`roundel/policy`'s `Runtime`, typed structurally):
     * the environment, whether stdout is a terminal, the colour flag the caller typed (`--no-color`,
     * `--color=always`; R1) and `quiet` (R2). Spread it into what you hand flagstaff's `hoist` or
     * roundel's `colorLevel`, and they decide colour and drawing the way the caller asked.
     */
    runtime: {
        env: Record<string, string | undefined>;
        argv: readonly string[];
        isTTY: {
            stdout: boolean;
        };
        quiet: boolean;
    };
}
```

### RunOptions

```ts
interface RunOptions {
    argv?: string[];
    /** Read by `--mcp`, which serves JSON-RPC over it; its `isTTY` is whether a person may be asked (N12). */
    stdin?: NodeJS.ReadableStream;
    /** The environment env-bound options read from. Injected by the harness; the process's own otherwise. */
    env?: Record<string, string | undefined>;
    /** `columns` is read when present, so help wraps to the terminal (H3); `isTTY` decides whether help is coloured (O2). */
    stdout?: {
        write: (s: string) => unknown;
        columns?: number;
        isTTY?: boolean;
    };
    /** `isTTY` decides whether a failure adds its structured line (clispec-conformance R6): absent is a pipe. */
    stderr?: {
        write: (s: string) => unknown;
        isTTY?: boolean;
    };
    /** Receives the E1 code. The default calls process.exit; an injected one may simply record it. */
    exit?: (code: number) => void;
    /** Where config discovery starts; the process's own otherwise. */
    cwd?: string;
    /** The entry file, whose nearest package.json owns the program's version (V4); `process.argv[1]` otherwise. */
    entry?: string;
    /**
     * The language help and refusals speak to a person, ahead of `BURGEE_LOCALE`, `LC_ALL`,
     * `LC_MESSAGES` and `LANG` (`localised-human-surfaces` R2). A BCP 47 tag, or `C` for the
     * program's own words; a registered plugin's `locales` supplies the translation. Machine
     * surfaces never read it (R3).
     */
    locale?: string;
}
```

### RunResult

```ts
interface RunResult {
    code: number;
    stdout: string;
    stderr: string;
}
```

### StandardSchemaV1

The Standard Schema interface (standardschema.dev), declared here so any implementation
— zod, valibot, arktype — is accepted as an option's `schema` without a dependency (S1).

```ts
interface StandardSchemaV1<Output = unknown> {
    readonly '~standard': {
        readonly version: 1;
        readonly vendor: string;
        readonly validate: (value: unknown) => StandardResult<Output> | Promise<StandardResult<Output>>;
    };
}
```

### Usage

The envelope's `error.usage`, and what the prose renders.

```ts
interface Usage {
    /** The command line from the program name: `demo greet [options] <name>`. */
    command: string;
    /** A runnable command's options, as typed. */
    options?: UsageRow[];
    /** A group's commands, for a word it does not know. */
    commands?: UsageRow[];
    /** The command that lists every row, present only when some were left out. */
    more?: string;
}
```

### UsageRow

```ts
interface UsageRow {
    /** `--code <value>`, `-n, --name <value>`, or a command word. */
    name: string;
    description: string;
}
```

## Types

### AnyCommand

```ts
type AnyCommand = Command<any, any, any>;
```

### Completer

D3 / D-119 — values computed when a person presses TAB. A completer that takes one parameter
is called as it always was; the second is the rest of the line (completion-context R1).

```ts
type Completer = (partial: string, context: CompletionContext) => Iterable<string> | Promise<Iterable<string>>;
```

### DeclaredArgument

A positional as declared (typed-positionals R1): `choices` on a string type only, as on an
option, so `{ type: 'number', choices: [...] }` is a type error here and a definition-time
error for a caller TypeScript does not check.

```ts
type DeclaredArgument = Omit<ArgumentSpec, 'type' | 'choices'> & ({
    type?: 'string';
    choices?: readonly string[];
} | {
    type: 'number' | 'integer' | 'boolean' | 'file';
    choices?: never;
});
```

### DeclaredExample

An example as declared: its description may be {@link Localised} (R5).

```ts
type DeclaredExample = Omit<Example, 'description'> & {
    description?: Localised;
};
```

### DeclaredOption

An option as declared: an {@link OptionSpec} whose description may be {@link Localised} (R5).

```ts
type DeclaredOption = Omit<OptionSpec, 'description'> & {
    description?: Localised;
};
```

### Effects

What running a command does to the world (N6). Declared, never inferred: it decides
whether the command is exposed as an MCP tool at all (N2) and generates the tool's
`readOnlyHint` / `idempotentHint` / `destructiveHint` — MCP defaults `destructiveHint`
to true, so silence is the dangerous reading.

```ts
type Effects = 'read_only' | 'idempotent' | 'non_idempotent';
```

### InferArgs

The handler's `args`, derived from the declaration (typed-positionals R2): keyed by name, a
variadic one an array, `number` and `integer` a number, `boolean` a boolean, `choices` a union,
and `| undefined` only on an optional one with no default. `any` stays `any`, so a list of
commands of different shapes (`AnyCommand`) still holds each of them.

```ts
type InferArgs<A extends readonly DeclaredArgument[]> = 0 extends 1 & A ? any : {
    [K in A[number] as K['name']]: K extends {
        variadic: true;
    } ? ArgValue<K>[] : ArgPresent<K> extends true ? ArgValue<K> : ArgValue<K> | undefined;
};
```

### InferOptions

The handler's `options`, derived from the declaration (S1): `choices` become a union, `multiple` an array, `number` a number.

```ts
type InferOptions<S extends Record<string, DeclaredOption>> = {
    [K in keyof S]: Present<S[K]> extends true ? Many<S[K], Scalar<S[K]>> : Many<S[K], Scalar<S[K]>> | undefined;
};
```

### Localised

`localised-human-surfaces` R5 — text an author writes in more than one language: one string, or
locale → text with the author's base language **first**. Help renders the run's locale (the
tag, then its bare language, then the base); `--schema`, `--mcp` and every other machine
surface carry the base language and nothing else, because a command's description there is
data a program reads, not prose (R3).

```ts
type Localised = string | Readonly<Record<string, string>>;
```

### OptionSpecs

```ts
type OptionSpecs = Record<string, DeclaredOption>;
```

### OutputOf

The TypeScript type a JSON Schema describes, for `run`'s return under `output.schema`: `const`,
`enum`, the scalar types, arrays by `items`, and objects by `properties`, with the keys in
`required` required and the rest optional. Anything it does not read is `unknown`, so a schema
it cannot follow never refuses a handler.

```ts
type OutputOf<J> = J extends {
    const: infer C;
} ? C : J extends {
    enum: readonly (infer E)[];
} ? E : J extends {
    type: 'string';
} ? string : J extends {
    type: 'number' | 'integer';
} ? number : J extends {
    type: 'boolean';
} ? boolean : J extends {
    type: 'null';
} ? null : J extends {
    type: 'array';
    items: infer I;
} ? OutputOf<I>[] : J extends {
    type: 'object';
    properties: infer P;
} ? ObjectOf<P, J extends {
    required: readonly (infer R)[];
} ? R : never> : unknown;
```

### OutputSchema

A JSON Schema, as far as `OutputOf` reads one: the shape is checked by the type below, and anything else is passed through.

```ts
type OutputSchema = Readonly<Record<string, unknown>>;
```

### Relation

A relationship between options, validated after parsing and before choices and the
handler (S2, S6). `implies` takes a second option name, or a predicate over the values.

```ts
type Relation = {
    exactlyOneOf: readonly string[];
} | {
    atLeastOneOf: readonly string[];
} | {
    atMostOneOf: readonly string[];
} | {
    conflicts: readonly string[];
} | {
    implies: readonly [string, string | ((values: Record<string, unknown>) => boolean)];
};
```

### StandardResult

```ts
type StandardResult<Output> = {
    readonly value: Output;
    readonly issues?: undefined;
} | {
    readonly issues: readonly {
        readonly message: string;
    }[];
};
```

## Re-exported

Documented on the page of the entry point that declares them.

| Export | Kind | Documented in |
| :-- | :-- | :-- |
| `isExitCode` | function | [`burgee/testing`](/docs/api/testing#isexitcode) |
| `Manifest` | class | [`burgee/schema`](/docs/api/schema#manifest) |
| `ExitCode` | const | [`burgee/testing`](/docs/api/testing#exitcode) |
| `ExitCodeValue` | const | [`burgee/testing`](/docs/api/testing#exitcodevalue) |
| `Candidate` | interface | [`burgee/config`](/docs/api/config#candidate) |
| `CommandSchema` | interface | [`burgee/schema`](/docs/api/schema#commandschema) |
| `HelpOptions` | interface | [`burgee/help`](/docs/api/help#helpoptions) |
| `JsonSchema` | interface | [`burgee/schema`](/docs/api/schema#jsonschema) |
| `Layers` | interface | [`burgee/config`](/docs/api/config#layers) |
| `Plugin` | interface | [`burgee/plugin`](/docs/api/plugin#plugin) |
| `ProgramSchema` | interface | [`burgee/schema`](/docs/api/schema#programschema) |
| `Provenance` | interface | [`burgee/config`](/docs/api/config#provenance) |
| `Resolution` | interface | [`burgee/config`](/docs/api/config#resolution) |
| `SchemaSummary` | interface | [`burgee/schema`](/docs/api/schema#schemasummary) |
| `ServeOptions` | interface | [`burgee/mcp`](/docs/api/mcp#serveoptions) |
| `Tool` | interface | [`burgee/mcp`](/docs/api/mcp#tool) |
| `ToolAnnotations` | interface | [`burgee/mcp`](/docs/api/mcp#toolannotations) |
| `HelpTheme` | type | [`burgee/help`](/docs/api/help#helptheme) |
| `HelpToken` | type | [`burgee/help`](/docs/api/help#helptoken) |
| `Invoke` | type | [`burgee/mcp`](/docs/api/mcp#invoke) |
| `LocaleMessages` | type | [`burgee/plugin`](/docs/api/plugin#localemessages) |
| `Locales` | type | [`burgee/plugin`](/docs/api/plugin#locales) |
| `Message` | type | [`burgee/plugin`](/docs/api/plugin#message) |
| `MessageId` | type | [`burgee/plugin`](/docs/api/plugin#messageid) |
| `PluginErrorCode` | type | [`burgee/plugin`](/docs/api/plugin#pluginerrorcode) |
| `Source` | type | [`burgee/config`](/docs/api/config#source) |

---

# burgee/mcp

> Every export of burgee/mcp, with its signature and doc comment: annotationsOf, MCP_PROTOCOL_VERSION, serveMcp, toolsOf, plus 4 types.

Source: https://burgee.interlace.tools/docs/api/mcp

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

`burgee/mcp` — the MCP server, by itself. See `index.ts` for why it is not in the barrel.

```ts
import { annotationsOf, MCP_PROTOCOL_VERSION, serveMcp, … } from 'burgee/mcp';
```

## Functions

### annotationsOf

MCP's hints, from the declared effects. `destructiveHint` is only ever false by declaration.

```ts
function annotationsOf(effects?: Effects): ToolAnnotations;
```

| Parameter | Type |
| :-- | :-- |
| `effects` (optional) | `Effects` |

**Returns** `ToolAnnotations`

### serveMcp

Serve until the input closes.

```ts
function serveMcp(manifest: Manifest, opts: ServeOptions): Promise<void>;
```

| Parameter | Type |
| :-- | :-- |
| `manifest` | `Manifest` |
| `opts` | `ServeOptions` |

**Returns** `Promise<void>`

### toolsOf

The tool list: every runnable, visible command an author has not withheld.

```ts
function toolsOf(manifest: Manifest): Tool[];
```

| Parameter | Type |
| :-- | :-- |
| `manifest` | `Manifest` |

**Returns** `Tool[]`

## Constants

### MCP_PROTOCOL_VERSION

The latest revision this server speaks, and the answer to a client asking for one it does not.

```ts
const MCP_PROTOCOL_VERSION = "2025-11-25";
```

## Interfaces

### ServeOptions

```ts
interface ServeOptions {
    input: NodeJS.ReadableStream;
    output: {
        write: (s: string) => unknown;
    };
    invoke: Invoke;
}
```

### Tool

```ts
interface Tool {
    name: string;
    description: string;
    inputSchema: JsonSchema;
    annotations: ToolAnnotations;
    /** The command's declared `output.schema`, as the shape of `structuredContent` (mcp-current R2). Absent when none is declared. */
    outputSchema?: OutputSchema;
}
```

### ToolAnnotations

```ts
interface ToolAnnotations {
    readOnlyHint?: boolean;
    idempotentHint?: boolean;
    destructiveHint?: boolean;
    /**
     * `'undeclared'`, and only ever that (G1). It appears on a command whose author said
     * nothing — every commander and yargs command that did not call `.effects()` — and never
     * beside a hint, because a hint is what a declaration produces.
     */
    effects?: 'undeclared';
}
```

## Types

### Invoke

What a tool call runs: the same execute a `--json` caller reaches, with the streams captured.

```ts
type Invoke = (argv: string[]) => Promise<{
    stdout: string;
    stderr: string;
    code: number;
}>;
```

---

# burgee/meow

> burgee/meow is a drop-in for meow: the same API, documented by meow itself. Every name it exports, and where its reference lives.

Source: https://burgee.interlace.tools/docs/api/meow

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts and burgee/src/compat.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

`burgee/meow` is a drop-in for `meow`, graded by the incumbent's own test suite. Its API is the incumbent's, so its reference is the incumbent's own documentation.

- **Reference:** [meow 14.1.0](https://www.npmjs.com/package/meow/v/14.1.0), the release that suite is run at.
- **How closely it matches:** [Compatibility](/docs/compatibility), that suite's result in CI, with every case left out of the gate and the reason.
- **Moving a program over:** [`burgee migrate`](/docs/migrate) rewrites `'meow'` to `'burgee/meow'` across a project.

## Exports

Every name `burgee/meow` exports, as the built declarations state them. Signatures and behaviour are meow's.

| Export | Kind |
| :-- | :-- |
| `default` | const |
| `AnyFlag` | type |
| `AnyFlags` | type |
| `Flag` | type |
| `FlagType` | type |
| `InputOption` | type |
| `InputOptionType` | type |
| `IsRequiredPredicate` | type |
| `Options` | type |
| `Result` | type |
| `TypedFlags` | type |

---

# burgee/plugin

> Every export of burgee/plugin, with its signature and doc comment: validate, definePlugin, CONTRACT, PluginError, plus 6 types.

Source: https://burgee.interlace.tools/docs/api/plugin

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

```ts
import { validate, definePlugin, CONTRACT, … } from 'burgee/plugin';
```

## Functions

### definePlugin

Declare a plugin: typed, validated, and stamped with the contract it was compiled against.

```ts
function definePlugin(plugin: Plugin): Plugin;
```

| Parameter | Type |
| :-- | :-- |
| `plugin` | `Plugin` |

**Returns** `Plugin`

### validate

Refuse a plugin that cannot contribute, at the door.

```ts
function validate(plugin: unknown, taken?: readonly string[]): asserts plugin is Plugin;
```

| Parameter | Type |
| :-- | :-- |
| `plugin` | `unknown` |
| `taken` (optional) | `readonly string[]` |

**Returns** `asserts plugin is Plugin`

## Classes

### PluginError

A refused plugin says what is wrong and what to do about it — the family's one vocabulary.

```ts
class PluginError extends Error {
    readonly code: PluginErrorCode;
    readonly fix: string;
    constructor(code: PluginErrorCode, message: string, fix: string);
}
```

## Constants

### CONTRACT

The plugin contract version. One number for the family — the same `1` flagstaff, caique and
closeout declare, written out rather than imported because a layer never imports a layer.

```ts
const CONTRACT = 1;
```

## Interfaces

### Plugin

The keys burgee reads. Declared structurally: any object with these fields is a plugin here,
whatever else it carries.

```ts
interface Plugin {
    name: string;
    contract?: number;
    commands?: CommandNode[];
    hooks?: Partial<Record<HookStage, Hook>>;
    enforce?: 'pre' | 'post';
    /**
     * A locale pack (`localised-human-surfaces` R4): language tag → catalog id → translation.
     * Not read at the door — `validate` lets it through like any other key — but checked where it
     * is first used, by the help or refusal it translates, and in full by `burgee check`, against
     * `burgee/locale-pack-schema.json`.
     */
    locales?: Locales;
}
```

## Types

### LocaleMessages

One language's translations, keyed by catalog id.

```ts
type LocaleMessages = Readonly<Partial<Record<MessageId, Message>>>;
```

### Locales

A pack's `locales`: BCP 47 tag → its messages. The whole of what a pack contributes.

```ts
type Locales = Readonly<Record<string, LocaleMessages>>;
```

### Message

A translation: one string, or — for a message that carries `{count}` — one per plural form.

```ts
type Message = string | Readonly<Partial<Record<Intl.LDMLPluralRule, string>>>;
```

### MessageId

A catalog id: what a pack keys its translations by.

```ts
type MessageId = keyof typeof MESSAGES;
```

### PluginErrorCode

```ts
type PluginErrorCode = 'E_PLUGIN_SCHEMA' | 'E_PLUGIN_CONTRACT' | 'E_NO_CONTRIBUTION';
```

---

# burgee/schema

> Every export of burgee/schema, with its signature and doc comment: commandSchemaOf, inputSchemaOf, schemaOf, summaryOf, Manifest, plus 4 types.

Source: https://burgee.interlace.tools/docs/api/schema

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

`burgee/schema` — the schema surface and the manifest it reads, by itself. See `index.ts`.

```ts
import { commandSchemaOf, inputSchemaOf, schemaOf, … } from 'burgee/schema';
```

## Functions

### commandSchemaOf

```ts
function commandSchemaOf(node: CommandNode, root: string[]): CommandSchema;
```

| Parameter | Type |
| :-- | :-- |
| `node` | `CommandNode` |
| `root` | `string[]` |

**Returns** `CommandSchema`

### inputSchemaOf

```ts
function inputSchemaOf(node: CommandNode): JsonSchema;
```

| Parameter | Type |
| :-- | :-- |
| `node` | `CommandNode` |

**Returns** `JsonSchema`

### schemaOf

```ts
function schemaOf(manifest: Manifest): ProgramSchema;
```

| Parameter | Type |
| :-- | :-- |
| `manifest` | `Manifest` |

**Returns** `ProgramSchema`

### summaryOf

Above the budget (N13): every command by name and summary, and the drilling command for one in full.

```ts
function summaryOf(manifest: Manifest, budget: number): SchemaSummary;
```

| Parameter | Type |
| :-- | :-- |
| `manifest` | `Manifest` |
| `budget` | `number` |

**Returns** `SchemaSummary`

## Classes

### Manifest

```ts
class Manifest {
    readonly commands: CommandNode[];
    readonly plugins: Plugin[];
    /** The program's own name, which the user never types; `execute` strips it. */
    rootPath: string[];
    /** Reported by `--schema`, `--version` and the MCP handshake; the owning package.json otherwise (V4). */
    version?: string;
    /** With a prefix, every option reads `PREFIX_OPTION_NAME` unless it names its own env (V2). */
    envPrefix?: string;
    /** Config discovery is opt-in; the name is the file stem and the package.json field (V6). */
    config?: {
        name: string;
    };
    /** Characters of `--schema` output above which it is summarised (N13). */
    schemaBudget?: number;
    /** The variable a non-interactive caller sets for the credential, when the program declares one (agent-lint-conformance R8). */
    auth?: {
        env: string;
    };
    add(node: CommandNode): void;
    /**
     * Register a plugin, after the plugin host has read it (`plugin.ts`).
     */
    use(plugin: Plugin): void;
    /** `enforce: 'pre'` first, then unordered, then `'post'` — the Vite/Rolldown convention. */
    private ordered;
    /** Whether any registered plugin declares a hook at `stage` — so a run without one pays nothing. */
    declares(stage: HookStage): boolean;
    /**
     * `parse` (D-122): argv in, argv out, before the command is resolved. Each plugin, in
     * `enforce` order, is handed what the previous one returned; returning nothing keeps it.
     * A filter is matched against the typed argv, since no command has been resolved yet.
     */
    parse(argv: string[]): Promise<string[]>;
    fire(stage: Exclude<HookStage, 'parse'>, command: string, options: Record<string, unknown>): Promise<void>;
    find(path: string[]): CommandNode | undefined;
    /**
     * Longest-prefix match of argv against declared command paths. The root's own
     * name is not typed by the user, so it is skipped when matching.
     */
    resolve(argv: string[], root?: string[]): {
        node: CommandNode | undefined;
        rest: string[];
    };
}
```

## Interfaces

### CommandSchema

```ts
interface CommandSchema {
    /** The command as typed, without the program name: `config get`. */
    name: string;
    description?: string;
    summary?: string;
    /** Other words that run it (R5): on the command, so a list of commands is one entry per command. */
    aliases?: readonly string[];
    /** It runs when argv names no command at its parent's level (default-command R4). */
    default?: boolean;
    /**
     * What running it does, or `'withheld'` — published either way, because an agent reading
     * the program as data is better served by *this exists and is not for you* than by a gap
     * it cannot tell from a command that does not exist (N6).
     */
    effects?: DeclaredEffects;
    /** What `--json=` selects from (N14), when the command declares it. */
    fields?: readonly string[];
    deprecated?: boolean | string;
    /** The heading it is listed under (M1). */
    group?: string;
    /** Its handler loads on dispatch (M2): this schema was complete without it. */
    lazy?: true;
    /** Which plugin contributed it (M3). */
    plugin?: string;
    excess?: true;
    arguments: ArgumentSpec[];
    options: Record<string, OptionSpec>;
    /**
     * The constraints between options (S2/S6), which `validate.ts` already enforces and the
     * schema did not publish. Without them an agent can only discover that `--a` conflicts
     * with `--b` by sending both and reading exit 2 — a round trip per constraint, and under
     * E1 an exit 2 means *rewrite the command*, so it may well send the same pair again.
     */
    relations?: PublishedRelation[];
    examples: Example[];
    /** The arguments and options as one JSON Schema object — what an MCP tool call takes. */
    inputSchema: JsonSchema;
}
```

### JsonSchema

```ts
interface JsonSchema {
    type: 'object';
    properties: Record<string, JsonSchemaProperty>;
    required: string[];
    additionalProperties: false;
}
```

### ProgramSchema

```ts
interface ProgramSchema {
    schemaVersion: 1;
    name: string;
    version?: string;
    description?: string;
    /**
     * F1 — what each exit code means, so an agent branches on the number without reading prose:
     * the contract's eight, the same table `ExitCode` exports.
     */
    exitCodes: Readonly<Record<string, number>>;
    /**
     * D-20261009-b1-totals-and-explain — how to ask where a value came from (`--explain`). A native
     * program's `--schema` carries it; `schemaOf` does not set it, so the façades' document is unchanged.
     */
    explain?: string;
    commands: CommandSchema[];
    /**
     * J4 — the reserved surfaces a façade program declares for itself, which burgee therefore
     * withholds: the program wins, and this says so rather than leaving a caller to find the
     * surface missing. Absent when it shadows none. A native program cannot shadow them —
     * `defineProgram` refuses the names (V5) — so only the commander and yargs façades set it.
     */
    shadows?: ('--json' | '--mcp' | 'completion')[];
}
```

### SchemaSummary

```ts
interface SchemaSummary {
    schemaVersion: 1;
    name: string;
    version?: string;
    description?: string;
    /** The full schema exceeded the budget; this lists every command and how to get one in full. */
    summarised: true;
    budget: number;
    commands: {
        name: string;
        summary?: string;
        effects?: DeclaredEffects;
    }[];
    hint: string;
    /** As on `ProgramSchema`. */
    explain?: string;
}
```

---

# burgee/testing

> Every export of burgee/testing, with its signature and doc comment: processRuntime, captureConsole, codeOf, fakeClock, fakeRuntime, finish and 7 more, plus 7 types.

Source: https://burgee.interlace.tools/docs/api/testing

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

`burgee/testing` — run a burgee CLI in-process, with argv, env, stdin, cwd and
TTY-ness injected, and get back `{ code, stdout, stderr, json }`. Requirement T1.

```ts
import { processRuntime, captureConsole, codeOf, … } from 'burgee/testing';
```

## Functions

### captureConsole

Route `console.*` into the fake runtime while a run lasts. Hosts print through
`console` in a few paths a public seam does not cover (yargs' help printer, a
handler that never met the output layer); a harness that let those reach the real
terminal would be measuring the wrong thing.

```ts
function captureConsole(rt: FakeRuntime): () => void;
```

| Parameter | Type |
| :-- | :-- |
| `rt` | `FakeRuntime` |

**Returns** `() => void`

### codeOf

The E1 code an unwound error carries, or `RUNTIME` when it carries none.

```ts
function codeOf(e: unknown): ExitCode;
```

| Parameter | Type |
| :-- | :-- |
| `e` | `unknown` |

**Returns** `ExitCode`

### fakeClock

Deterministic time for the harness. Starts at `start` (0 by default) and never moves on its own.

```ts
function fakeClock(start?: number): FakeClock;
```

| Parameter | Type |
| :-- | :-- |
| `start` (optional) | `number` |

**Returns** `FakeClock`

### fakeRuntime

A `Runtime` whose every part is under the test's control.

```ts
function fakeRuntime(opts: RunOptions): FakeRuntime;
```

| Parameter | Type |
| :-- | :-- |
| `opts` | `RunOptions` |

**Returns** `FakeRuntime`

### finish

Assemble the result (R2). `json` is set only when `--json` was in argv and stdout
parsed; a parse failure turns the run into `RUNTIME` with the parse error on
stderr, so a broken envelope cannot pass a test by accident.

```ts
function finish(rt: FakeRuntime, code: ExitCode, startedAt: number): RunResult;
```

| Parameter | Type |
| :-- | :-- |
| `rt` | `FakeRuntime` |
| `code` | `ExitCode` |
| `startedAt` | `number` |

**Returns** `RunResult`

### isExitCode

True for the eight codes in the contract and nothing else. The set holds numbers only, so it
answers `false` for `'2'` or any other non-number by itself; the `typeof` guard this used to
carry was the 27 bytes that paid for `TIMEOUT` on every entry that reaches this file.

```ts
function isExitCode(n: unknown): n is ExitCode;
```

| Parameter | Type |
| :-- | :-- |
| `n` | `unknown` |

**Returns** `n is ExitCode`

### runBurgee

Run a burgee program in-process — the T1 harness for burgee itself. Env is injected,
never swapped: the engine reads env-bound options from the runtime it is given, so
`process.env` is untouched by construction. Exit unwinds through `RuntimeExit`.

```ts
function runBurgee(program: Manifest, opts: RunOptions): Promise<RunResult>;
```

| Parameter | Type |
| :-- | :-- |
| `program` | `Manifest` |
| `opts` | `RunOptions` |

**Returns** `Promise<RunResult>`

### stripAnsi

Strip ANSI escape sequences — the decision from the intent: `stdout` stays raw.

```ts
function stripAnsi(text: string): string;
```

| Parameter | Type |
| :-- | :-- |
| `text` | `string` |

**Returns** `string`

### swapEnv

```ts
function swapEnv(env: Record<string, string> | undefined): () => void;
```

| Parameter | Type |
| :-- | :-- |
| `env` | `Record<string, string> \| undefined` |

**Returns** `() => void`

## Classes

### RuntimeExit

Thrown by `fakeRuntime.exit` so a handler that exits unwinds to the harness.

```ts
class RuntimeExit extends Error {
    readonly code: ExitCode;
    constructor(code: ExitCode);
}
```

## Constants

### ExitCode

E1 — exit codes are a contract. No other literal may reach `process.exitCode`.

```ts
const ExitCode: {
    /** Command completed. */
    readonly OK: 0;
    /** The command ran and failed. Never accompanied by help text (E2). */
    readonly RUNTIME: 1;
    /** Bad arguments, unknown command, missing flag, prompt needed in a non-TTY (P2). */
    readonly USAGE: 2;
    /** Config file or environment could not be loaded or validated (V1). */
    readonly CONFIG: 3;
    /** The user or caller cancelled. */
    readonly CANCELLED: 4;
    /**
     * E6 — the far side said no: a credential is missing, expired, or refused.
     */
    readonly AUTH: 5;
    /**
     * agent-lint-conformance R3 — the deadline `--timeout` set has passed: retry with more time.
     */
    readonly TIMEOUT: 6;
    /** SIGINT after the terminal was restored (E5). */
    readonly SIGINT: 130;
};

type ExitCode = (typeof ExitCode)[keyof typeof ExitCode];
```

### ExitCodeValue

E1 — exit codes are a contract. No other literal may reach `process.exitCode`.

```ts
const ExitCode: {
    /** Command completed. */
    readonly OK: 0;
    /** The command ran and failed. Never accompanied by help text (E2). */
    readonly RUNTIME: 1;
    /** Bad arguments, unknown command, missing flag, prompt needed in a non-TTY (P2). */
    readonly USAGE: 2;
    /** Config file or environment could not be loaded or validated (V1). */
    readonly CONFIG: 3;
    /** The user or caller cancelled. */
    readonly CANCELLED: 4;
    /**
     * E6 — the far side said no: a credential is missing, expired, or refused.
     */
    readonly AUTH: 5;
    /**
     * agent-lint-conformance R3 — the deadline `--timeout` set has passed: retry with more time.
     */
    readonly TIMEOUT: 6;
    /** SIGINT after the terminal was restored (E5). */
    readonly SIGINT: 130;
};

type ExitCode = (typeof ExitCode)[keyof typeof ExitCode];
```

### processRuntime

The real `Runtime`, for a caller that injects none.

```ts
const processRuntime: Runtime;
```

## Interfaces

### Clock

Time, as the layers above the parser see it (R14 of `cli-output-stack`). `now` is
monotonic milliseconds from an arbitrary origin; `schedule` runs `fn` after `ms` and
hands back the cancel. Typed structurally so the output stack can accept a `Runtime`
without importing one.

```ts
interface Clock {
    now(): number;
    schedule(fn: () => void, ms: number): () => void;
}
```

### FakeClock

A `Clock` that moves only when the test says so (R14): `tick` is the only source of time.

```ts
interface FakeClock extends Clock {
    /**
     * Advance by `ms`, running every callback that falls due, earliest first, then by order
     * scheduled. A callback that schedules inside the window runs in the same tick, so one that
     * reschedules itself at `0` would never leave the loop (real Node yields between turns);
     * a tick runs at most `TICK_CAP` callbacks and throws, naming the cap, when exceeded.
     */
    tick(ms: number): void;
    /** Callbacks scheduled and neither run nor cancelled. */
    pending(): number;
}
```

### FakeRuntime

```ts
interface FakeRuntime extends Runtime {
    out: string[];
    err: string[];
    clock: FakeClock;
}
```

### RunOptions

```ts
interface RunOptions {
    argv: string[];
    env?: Record<string, string>;
    stdin?: string | Readable;
    cwd?: string;
    /** `true` = every stream is a TTY; an object sets each; default: none is. */
    tty?: boolean | Partial<Runtime['isTTY']>;
    /** The clock the runtime reports; a fresh `fakeClock()` at 0 when not given. */
    clock?: FakeClock;
}
```

### RunResult

```ts
interface RunResult {
    code: ExitCode;
    stdout: string;
    stderr: string;
    /** Parsed stdout when `--json` was in argv and stdout parsed; see `finish`. */
    json?: unknown;
    durationMs: number;
}
```

### Runtime

The world, as the layers above the parser see it (design R1 of
`cli-testing-harness`). Nothing above the parser reads `process.*` directly; it
reads its `Runtime`, so a test can substitute every part of it.

```ts
interface Runtime {
    argv: string[];
    env: Record<string, string | undefined>;
    cwd: string;
    stdin: NodeJS.ReadableStream;
    stdout: Writer;
    stderr: Writer;
    isTTY: {
        stdin: boolean;
        stdout: boolean;
        stderr: boolean;
    };
    /** Ends the run with an E1 code. In the real runtime this never returns. */
    exit(code: ExitCode): never;
    /** `performance.now` and `setTimeout` in the real runtime; a manual tick in the harness. */
    clock: Clock;
}
```

### Writer

Anything that accepts text; `process.stdout` satisfies it, so does an array push.

```ts
interface Writer {
    write(chunk: string): unknown;
}
```

---

# burgee/yargs

> burgee/yargs is a drop-in for yargs: the same API, documented by yargs itself. Every name it exports, and where its reference lives.

Source: https://burgee.interlace.tools/docs/api/yargs

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts and burgee/src/compat.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

`burgee/yargs` is a drop-in for `yargs`, graded by the incumbent's own test suite. Its API is the incumbent's, so its reference is the incumbent's own documentation.

- **Reference:** [yargs 18.2.0](https://www.npmjs.com/package/yargs/v/18.2.0), the release that suite is run at.
- **How closely it matches:** [Compatibility](/docs/compatibility), that suite's result in CI, with every case left out of the gate and the reason.
- **Switching:** [Switching from yargs](/docs/vs/yargs).
- **Moving a program over:** [`burgee migrate`](/docs/migrate) rewrites `'yargs'` to `'burgee/yargs'` across a project.

## Exports

Every name `burgee/yargs` exports, as the built declarations state them. Signatures and behaviour are yargs's.

| Export | Kind |
| :-- | :-- |
| `default` | const |
| `applyExtends` | function |
| `argsert` | function |
| `camelCase` | function |
| `decamelize` | function |
| `hideBin` | function |
| `isPromise` | function |
| `isYargsInstance` | function |
| `looksLikeNumber` | function |
| `objFilter` | function |
| `parseCommand` | function |
| `YargsInstance` | class |
| `YError` | class |
| `module.exports` | const |
| `platformShim` | const |
| `Argv` | interface |
| `CommandModule` | interface |
| `DetailedArguments` | interface |
| `Options` | interface |
| `ParsedCommand` | interface |
| `Parser` | interface |
| `PlatformShim` | interface |
| `PositionalOptions` | interface |
| `RequireDirectoryOptions` | interface |
| `Arguments` | type |
| `ArgumentsCamelCase` | type |
| `AsyncCompletionFunction` | type |
| `BuilderArguments` | type |
| `BuilderCallback` | type |
| `Choices` | type |
| `CommandBuilder` | type |
| `CompletionCallback` | type |
| `Defined` | type |
| `FallbackCompletionFunction` | type |
| `InferredOptionType` | type |
| `InferredOptionTypeInner` | type |
| `InferredOptionTypePrimitive` | type |
| `InferredOptionTypes` | type |
| `MiddlewareFunction` | type |
| `ParseCallback` | type |
| `ParserConfigurationOptions` | type |
| `PositionalOptionsType` | type |
| `PromiseCompletionFunction` | type |
| `SyncCompletionFunction` | type |
| `ToArray` | type |
| `ToNumber` | type |
| `ToString` | type |

---

# burgee/yargs/helpers

> burgee/yargs/helpers is a drop-in for yargs/helpers: the same API, documented by yargs itself. Every name it exports, and where its reference lives.

Source: https://burgee.interlace.tools/docs/api/yargs/helpers

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts and burgee/src/compat.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

`burgee/yargs/helpers` is a drop-in for `yargs/helpers`, graded by the incumbent's own test suite. Its API is the incumbent's, so its reference is the incumbent's own documentation.

- **Reference:** [yargs 18.2.0](https://www.npmjs.com/package/yargs/v/18.2.0), the release that suite is run at.
- **How closely it matches:** [Compatibility](/docs/compatibility), that suite's result in CI, with every case left out of the gate and the reason.
- **Switching:** [Switching from yargs](/docs/vs/yargs).
- **Moving a program over:** [`burgee migrate`](/docs/migrate) rewrites `'yargs/helpers'` to `'burgee/yargs/helpers'` across a project.

## Exports

Every name `burgee/yargs/helpers` exports, as the built declarations state them. Signatures and behaviour are yargs's.

| Export | Kind |
| :-- | :-- |
| `applyExtends` | function |
| `hideBin` | function |
| `Parser` | interface |

---

# burgee/yargs/parser

> burgee/yargs/parser is a drop-in for yargs-parser: the same API, documented by yargs-parser itself. Every name it exports, and where its reference lives.

Source: https://burgee.interlace.tools/docs/api/yargs/parser

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts and burgee/src/compat.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

`burgee/yargs/parser` is a drop-in for `yargs-parser`, graded by the incumbent's own test suite. Its API is the incumbent's, so its reference is the incumbent's own documentation.

- **Reference:** [yargs-parser 22.0.0](https://www.npmjs.com/package/yargs-parser/v/22.0.0), the release that suite is run at.
- **How closely it matches:** [Compatibility](/docs/compatibility), that suite's result in CI, with every case left out of the gate and the reason.
- **Switching:** [Switching from yargs](/docs/vs/yargs).
- **Moving a program over:** [`burgee migrate`](/docs/migrate) rewrites `'yargs-parser'` to `'burgee/yargs/parser'` across a project.

## Exports

Every name `burgee/yargs/parser` exports, as the built declarations state them. Signatures and behaviour are yargs-parser's.

| Export | Kind |
| :-- | :-- |
| `default` | const |
| `camelCase` | function |
| `decamelize` | function |
| `looksLikeNumber` | function |
| `tokenizeArgString` | function |
| `YargsParser` | class |
| `module.exports` | const |
| `Parser` | const |
| `Arguments` | interface |
| `DetailedArguments` | interface |
| `ParserMixin` | interface |
| `Configuration` | type |
| `Options` | type |

---

# burgee/yargs/v17

> Every export of burgee/yargs/v17, with its signature and doc comment: applyExtends, argsert, camelCase, decamelize, hideBin, isPromise and 8 more, plus 32 types.

Source: https://burgee.interlace.tools/docs/api/yargs/v17

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

`burgee/yargs/v17` — `burgee/yargs` for a program on yargs 17, the entry `burgee migrate`
writes for one (`previous-majors` R3, R4). `import` reaches this file: 17's `index.mjs`, the
factory, with 17's string table and `commandDir()` (`v17-factory.ts`). `require()` reaches
`v17.cjs`, 17's singleton.

```ts
import Yargs17 from 'burgee/yargs/v17';
import { applyExtends, argsert, camelCase, … } from 'burgee/yargs/v17';
```

## Functions

### applyExtends

`extends` in a config object. The upstream resolves a bare specifier with
`import.meta.resolve` and then loads it through `require`; both are done from here.

```ts
function applyExtends(config: Record<string, any>, cwd: string, mergeExtends?: boolean): Record<string, any>;
```

| Parameter | Type |
| :-- | :-- |
| `config` | `Record<string, any>` |
| `cwd` | `string` |
| `mergeExtends` (optional) | `boolean` |

**Returns** `Record<string, any>`

### argsert

```ts
function argsert(arg1: string | any[], arg2?: any, arg3?: number): void;
```

| Parameter | Type |
| :-- | :-- |
| `arg1` | `string \| any[]` |
| `arg2` (optional) | `any` |
| `arg3` (optional) | `number` |

**Returns** `void`

### camelCase

```ts
function camelCase(str: string): string;
```

| Parameter | Type |
| :-- | :-- |
| `str` | `string` |

**Returns** `string`

### decamelize

```ts
function decamelize(str: string, joinString?: string): string;
```

| Parameter | Type |
| :-- | :-- |
| `str` | `string` |
| `joinString` (optional) | `string` |

**Returns** `string`

### hideBin

```ts
function hideBin(argv: string[]): string[];
```

| Parameter | Type |
| :-- | :-- |
| `argv` | `string[]` |

**Returns** `string[]`

### isPromise

```ts
function isPromise(maybePromise: any): maybePromise is Promise<any>;
```

| Parameter | Type |
| :-- | :-- |
| `maybePromise` | `any` |

**Returns** `maybePromise is Promise<any>`

### isYargsInstance

```ts
function isYargsInstance(y: any): y is YargsInstance;
```

| Parameter | Type |
| :-- | :-- |
| `y` | `any` |

**Returns** `y is YargsInstance`

### looksLikeNumber

```ts
function looksLikeNumber(x: any): boolean;
```

| Parameter | Type |
| :-- | :-- |
| `x` | `any` |

**Returns** `boolean`

### objFilter

```ts
function objFilter<T extends object>(original?: T, filter?: (k: string, v: any) => boolean): T;
```

| Parameter | Type |
| :-- | :-- |
| `original` (optional) | `T` |
| `filter` (optional) | `(k: string, v: any) => boolean` |

**Returns** `T`

### parseCommand

```ts
function parseCommand(cmd: string): ParsedCommand;
```

| Parameter | Type |
| :-- | :-- |
| `cmd` | `string` |

**Returns** `ParsedCommand`

## Classes

### YargsInstance

```ts
class YargsInstance {
    #private;
    $0: string;
    argv?: any;
    customScriptName: boolean;
    parsed: any;
    constructor(processArgs: string | string[] | undefined, cwd: string, parentRequire: NodeJS.Require | undefined, shim: PlatformShim);
    addHelpOpt(opt?: string | false, msg?: string): this;
    help(opt?: string | false, msg?: string): this;
    addShowHiddenOpt(opt?: string | false, msg?: string): this;
    showHidden(opt?: string | false, msg?: string): this;
    alias(key: string | string[] | Record<string, string | string[]>, value?: string | string[]): this;
    array(keys: string | string[]): this;
    boolean(keys: string | string[]): this;
    check(f: (argv: any, options: Options) => any, global?: boolean): this;
    choices(key: string | string[] | Record<string, any>, value?: any): this;
    coerce(keys: string | string[] | Record<string, (arg: any) => any>, value?: (arg: any) => any): this;
    conflicts(key1: string | Record<string, string | string[]>, key2?: string | string[]): this;
    config(key?: string | string[] | Record<string, any>, msg?: string | ((path: string) => any), parseFn?: (path: string) => any): this;
    completion(cmd?: string, desc?: string | false | CompletionFunction, fn?: CompletionFunction): this;
    command(cmd: any, description?: any, builder?: any, handler?: any, middlewares?: Middleware[], deprecated?: boolean | string): this;
    commands(cmd: any, description?: any, builder?: any, handler?: any, middlewares?: Middleware[], deprecated?: boolean | string): this;
    commandDir(dir: string, opts?: any): this;
    count(keys: string | string[]): this;
    default(key: string | string[] | Record<string, any>, value?: any, defaultDescription?: string): this;
    defaults(key: string | string[] | Record<string, any>, value?: any, defaultDescription?: string): this;
    demandCommand(min?: number, max?: number | string | null, minMsg?: string | null, maxMsg?: string | null): this;
    demand(keys: string | string[] | number | Record<string, any>, max?: number | string | string[] | boolean, msg?: string | boolean): this;
    demandOption(keys: string | string[] | Record<string, string | undefined>, msg?: string): this;
    deprecateOption(option: string, message?: string | boolean): this;
    describe(keys: string | string[] | Record<string, string>, description?: string): this;
    detectLocale(detect: boolean): this;
    env(prefix?: string | false): this;
    epilogue(msg: string): this;
    epilog(msg: string): this;
    example(cmd: string | [string, string?][], description?: string): this;
    exit(code: number, err?: YError | string): void;
    exitProcess(enabled?: boolean): this;
    fail(f: FailureFunction | boolean): this;
    getAliases(): Record<string, string[]>;
    getCompletion(args: string[], done?: (err: Error | null, completions: string[] | undefined) => void): Promise<string[] | void>;
    getDemandedOptions(): Record<string, string | undefined>;
    getDemandedCommands(): Options['demandedCommands'];
    getDeprecatedOptions(): Options['deprecatedOptions'];
    getDetectLocale(): boolean;
    getExitProcess(): boolean;
    getGroups(): Record<string, string[]>;
    getHelp(): Promise<string>;
    getOptions(): Options;
    getStrict(): boolean;
    getStrictCommands(): boolean;
    getStrictOptions(): boolean;
    global(globals: string | string[], global?: boolean): this;
    group(opts: string | string[], groupName: string): this;
    hide(key: string): this;
    implies(key: string | Record<string, any>, value?: number | string | string[]): this;
    locale(locale?: string): this | string;
    middleware(callback: Middleware | Middleware[], applyBeforeValidation?: boolean, global?: boolean): this;
    nargs(key: string | string[] | Record<string, number>, value?: number): this;
    normalize(keys: string | string[]): this;
    number(keys: string | string[]): this;
    option(key: string | Record<string, any>, opt?: any): this;
    options(key: string | Record<string, any>, opt?: any): this;
    parse(args?: string | string[], shortCircuit?: object | ParseCallback | boolean, _parseFn?: ParseCallback): any;
    parseAsync(args?: string | string[], shortCircuit?: object | ParseCallback | boolean, _parseFn?: ParseCallback): Promise<any>;
    parseSync(args?: string | string[], shortCircuit?: object | ParseCallback | boolean, _parseFn?: ParseCallback): any;
    parserConfiguration(config: Record<string, any>): this;
    pkgConf(key: string, rootPath?: string): this;
    positional(key: string, opts: Record<string, any>): this;
    recommendCommands(recommend?: boolean): this;
    required(keys: string | string[] | number | Record<string, any>, max?: number | string | string[] | boolean, msg?: string | boolean): this;
    require(keys: string | string[] | number | Record<string, any>, max?: number | string | string[] | boolean, msg?: string | boolean): this;
    requiresArg(keys: string | string[] | Record<string, any>): this;
    showCompletionScript($0?: string, cmd?: string): this;
    showHelp(level?: 'error' | 'log' | ((message: string) => void)): this;
    scriptName(scriptName: string): this;
    showHelpOnFail(enabled?: string | boolean, message?: string): this;
    showVersion(level?: 'error' | 'log' | ((message: string) => void)): this;
    skipValidation(keys: string | string[]): this;
    strict(enabled?: boolean): this;
    strictCommands(enabled?: boolean): this;
    strictOptions(enabled?: boolean): this;
    string(keys: string | string[]): this;
    terminalWidth(): number | null;
    updateLocale(obj: Record<string, any>): this;
    updateStrings(obj: Record<string, any>): this;
    usage(msg: string | null, description?: string | false, builder?: any, handler?: any): this;
    usageConfiguration(config: Record<string, any>): this;
    version(opt?: string | false, msg?: string, ver?: string): this;
    wrap(cols: number | null | undefined): this;
    getInternalMethods(): {
        getCommandInstance: () => CommandInstance;
        getContext: () => Context;
        getHasOutput: () => boolean;
        getLoggerInstance: () => Logger;
        getParseContext: () => object;
        getParserConfiguration: () => Record<string, any>;
        getUsageConfiguration: () => Record<string, any>;
        getUsageInstance: () => UsageInstance;
        getValidationInstance: () => ValidationInstance;
        hasParseCallback: () => boolean;
        isGlobalContext: () => boolean;
        postProcess: (argv: any, populateDoubleDash: boolean, calledFromCommand: boolean, runGlobalMiddleware: boolean) => any;
        reset: (aliases?: Record<string, string[]>) => YargsInstance;
        runValidation: (aliases: Record<string, string[]>, positionalMap: Record<string, string[]>, parseErrors: Error | null, isDefaultCommand?: boolean) => (argv: any) => void;
        runYargsParserAndExecuteCommands: (args: string | string[] | null, shortCircuit?: boolean, calledFromCommand?: boolean, commandIndex?: number, helpOnly?: boolean) => any;
        setHasOutput: () => void;
        runHandler: (handler: (argv: any) => any, argv: any, original: string) => any;
    };
    /**
     * The manifest every surface reads (J7, J8). Projected on each access from what the
     * program registered; a command's builder is run on a scratch instance to learn its
     * options, exactly as yargs' own completion does. Plugin-contributed nodes are kept.
     */
    get manifest(): Manifest;
    /** burgee: declare what the command does to the world (N6); what exposes it as an MCP tool (N2). */
    effects(value: DeclaredEffects): this;
    /** Additive: plugins yargs never had. `preRun`/`postRun` fire around every handler. */
    use(plugin: Plugin): this;
    /**
     * Inject the streams and the exit for this instance (T1). Output goes to `stdout`/`stderr`
     * instead of the console, and `exit` receives an E1 code: OK for help and version, USAGE
     * for a validation failure, RUNTIME for a handler that threw.
     */
    burgee({ floor, ...seam }: BurgeeSeam): this;
}
```

### YError

yargs' small internal modules — yerror, parse-command, argsert, obj-filter, is-promise,
levenshtein, maybe-async-result, set-blocking, apply-extends, process-argv — ported
for `burgee/yargs`. Its suite imports four of these by their upstream file paths; the
oracle shims those paths to this entry, so the names here are the upstream names.

```ts
class YError extends Error {
    constructor(msg?: string | null);
}
```

## Constants

### default

The default export, declared as `Yargs17`.

17's `index.mjs`: the factory, over a string table of its own (`v17-factory.ts`).

```ts
const Yargs17: typeof Yargs;
```

### platformShim

```ts
const shim: PlatformShim;
```

## Interfaces

### Argv

The type parameter `T` is the expected shape of the parsed options.
`Arguments<T>` is those options plus `_` and `$0`, and an indexer falling
back to `unknown` for unknown options.

```ts
interface Argv<T = {}> {
    /**
     * Set key names as equivalent such that updates to a key will propagate to aliases and vice-versa.
     */
    alias<K1 extends keyof T, K2 extends string>(shortName: K1, longName: K2 | readonly K2[]): Argv<T & {
        [key in K2]: T[K1];
    }>;
    alias<K1 extends keyof T, K2 extends string>(shortName: K2, longName: K1 | readonly K1[]): Argv<T & {
        [key in K2]: T[K1];
    }>;
    alias(shortName: string | readonly string[], longName: string | readonly string[]): Argv<T>;
    alias(aliases: {
        [shortName: string]: string | readonly string[];
    }): Argv<T>;
    /**
     * Get the arguments as a plain old object.
     */
    argv: {
        [key in keyof Arguments<T> as key | CamelCaseKey<key>]: Arguments<T>[key];
    } | Promise<{
        [key in keyof Arguments<T> as key | CamelCaseKey<key>]: Arguments<T>[key];
    }>;
    /**
     * Tell the parser to interpret `key` as an array.
     * If `.array('foo')` is set, `--foo foo bar` will be parsed as `['foo', 'bar']` rather than as `'foo'`.
     * Also, if you use the option multiple times all the values will be flattened in one array so `--foo foo --foo bar` will be parsed as `['foo', 'bar']`
     */
    array<K extends keyof T>(key: K | readonly K[]): Argv<Omit<T, K> & {
        [key in K]: ToArray<T[key]>;
    }>;
    array<K extends string>(key: K | readonly K[]): Argv<T & {
        [key in K]: Array<string | number> | undefined;
    }>;
    /**
     * Interpret `key` as a boolean. If a non-flag option follows `key` in `process.argv`, that string won't get set as the value of `key`.
     */
    boolean<K extends keyof T>(key: K | readonly K[]): Argv<Omit<T, K> & {
        [key in K]: boolean | undefined;
    }>;
    boolean<K extends string>(key: K | readonly K[]): Argv<T & {
        [key in K]: boolean | undefined;
    }>;
    /**
     * Check that certain conditions are met in the provided arguments.
     * @param func Called with two arguments, the parsed `argv` hash and an array of options and their aliases.
     * If `func` throws or returns a non-truthy value, show the thrown error, usage information, and exit.
     * @param global Indicates whether `check()` should be enabled both at the top-level and for each sub-command.
     */
    check(func: (argv: Arguments<T>, aliases: {
        [alias: string]: string;
    }) => any, global?: boolean): Argv<T>;
    /**
     * Limit valid values for key to a predefined set of choices, given as an array or as an individual value.
     * If this method is called multiple times, all enumerated values will be merged together.
     * Choices are generally strings or numbers, and value matching is case-sensitive.
     */
    choices<K extends keyof T, C extends readonly any[]>(key: K, values: C): Argv<Omit<T, K> & {
        [key in K]: C[number] | undefined;
    }>;
    choices<K extends string, C extends readonly any[]>(key: K, values: C): Argv<T & {
        [key in K]: C[number] | undefined;
    }>;
    choices<C extends {
        [key: string]: readonly any[];
    }>(choices: C): Argv<Omit<T, keyof C> & {
        [key in keyof C]: C[key][number] | undefined;
    }>;
    /**
     * Provide a synchronous function to coerce or transform the value(s) given on the command line for `key`.
     */
    coerce<K extends keyof T, V>(key: K | readonly K[], func: (arg: any) => V): Argv<Omit<T, K> & {
        [key in K]: V | undefined;
    }>;
    coerce<K extends string, V>(key: K | readonly K[], func: (arg: any) => V): Argv<T & {
        [key in K]: V | undefined;
    }>;
    coerce<O extends {
        [key: string]: (arg: any) => any;
    }>(opts: O): Argv<Omit<T, keyof O> & {
        [key in keyof O]: ReturnType<O[key]> | undefined;
    }>;
    /**
     * Define the commands exposed by your application.
     * @param command Should be a string representing the command or an array of strings representing the command and its aliases.
     * @param description Use to provide a description for each command your application accepts (the values stored in `argv._`).
     * Set `description` to false to create a hidden command. Hidden commands don't show up in the help output and aren't available for completion.
     * @param [builder] Object to give hints about the options that your command accepts.
     * Can also be a function. This function is executed with a yargs instance, and can be used to provide advanced command specific help.
     *
     * Note that when `void` is returned, the handler `argv` object type will not include command-specific arguments.
     * @param [handler] Function, which will be executed with the parsed `argv` object.
     */
    command<U = T>(command: string | readonly string[], description: string, builder?: BuilderCallback<T, U>, handler?: (args: ArgumentsCamelCase<U>) => unknown, middlewares?: Array<MiddlewareFunction<U>>, deprecated?: boolean | string): Argv<T>;
    command<O extends {
        [key: string]: Options;
    }>(command: string | readonly string[], description: string, builder?: O, handler?: (args: ArgumentsCamelCase<InferredOptionTypes<O>>) => unknown, middlewares?: Array<MiddlewareFunction<O>>, deprecated?: boolean | string): Argv<T>;
    command<U = any>(command: string | readonly string[], description: string, module: CommandModule<T, U>): Argv<T>;
    command<U = T>(command: string | readonly string[], showInHelp: false, builder?: BuilderCallback<T, U>, handler?: (args: ArgumentsCamelCase<U>) => unknown, middlewares?: Array<MiddlewareFunction<U>>, deprecated?: boolean | string): Argv<T>;
    command<O extends {
        [key: string]: Options;
    }>(command: string | readonly string[], showInHelp: false, builder?: O, handler?: (args: ArgumentsCamelCase<InferredOptionTypes<O>>) => unknown): Argv<T>;
    command<U = any>(command: string | readonly string[], showInHelp: false, module: CommandModule<T, U>): Argv<T>;
    command<U = any>(module: CommandModule<T, U>): Argv<T>;
    command<U = any>(modules: Array<CommandModule<T, U>>): Argv<T>;
    /** Apply command modules from a directory relative to the module calling this method. */
    commandDir(dir: string, opts?: RequireDirectoryOptions): Argv<T>;
    /**
     * Enable bash/zsh-completion shortcuts for commands and options.
     * @param [cmd] When present in `argv._`, will result in the `.bashrc` or `.zshrc` completion script being outputted.
     * To enable bash/zsh completions, concat the generated script to your `.bashrc` or `.bash_profile` (or `.zshrc` for zsh).
     * @param [description] Provide a description in your usage instructions for the command that generates the completion scripts.
     * @param [func] Rather than relying on yargs' default completion functionality, which shiver me timbers is pretty awesome, you can provide your own completion method.
     */
    completion(): Argv<T>;
    completion(cmd: string, func?: AsyncCompletionFunction): Argv<T>;
    completion(cmd: string, func?: SyncCompletionFunction): Argv<T>;
    completion(cmd: string, func?: PromiseCompletionFunction): Argv<T>;
    completion(cmd: string, func?: FallbackCompletionFunction): Argv<T>;
    completion(cmd: string, description?: string | false, func?: AsyncCompletionFunction): Argv<T>;
    completion(cmd: string, description?: string | false, func?: SyncCompletionFunction): Argv<T>;
    completion(cmd: string, description?: string | false, func?: PromiseCompletionFunction): Argv<T>;
    completion(cmd: string, description?: string | false, func?: FallbackCompletionFunction): Argv<T>;
    /**
     * Tells the parser that if the option specified by `key` is passed in, it should be interpreted as a path to a JSON config file.
     * The file is loaded and parsed, and its properties are set as arguments.
     * Because the file is loaded using Node's require(), the filename MUST end in `.json` to be interpreted correctly.
     * @param [description] Provided to customize the config (`key`) option in the usage string.
     * @param [explicitConfigurationObject] An explicit configuration `object`
     */
    config(): Argv<T>;
    config(key: string | readonly string[], description?: string, parseFn?: (configPath: string) => object): Argv<T>;
    config(key: string | readonly string[], parseFn: (configPath: string) => object): Argv<T>;
    config(explicitConfigurationObject: object): Argv<T>;
    /**
     * Given the key `x` is set, the key `y` must not be set. `y` can either be a single string or an array of argument names that `x` conflicts with.
     */
    conflicts(key: string, value: string | readonly string[]): Argv<T>;
    conflicts(conflicts: {
        [key: string]: string | readonly string[];
    }): Argv<T>;
    /**
     * Interpret `key` as a boolean flag, but set its parsed value to the number of flag occurrences rather than `true` or `false`. Default value is thus `0`.
     */
    count<K extends keyof T>(key: K | readonly K[]): Argv<Omit<T, K> & {
        [key in K]: number;
    }>;
    count<K extends string>(key: K | readonly K[]): Argv<T & {
        [key in K]: number;
    }>;
    /**
     * Set `argv[key]` to `value` if no option was specified in `process.argv`.
     */
    default<K extends keyof T, V>(key: K, value: V, description?: string): Argv<Omit<T, K> & {
        [key in K]: V;
    }>;
    default<K extends string, V>(key: K, value: V, description?: string): Argv<T & {
        [key in K]: V;
    }>;
    default<D extends {
        [key: string]: any;
    }>(defaults: D, description?: string): Argv<Omit<T, keyof D> & D>;
    /**
     * @deprecated since version 6.6.0
     * Use '.demandCommand()' or '.demandOption()' instead
     */
    demand<K extends keyof T>(key: K | readonly K[], msg?: string | true): Argv<Defined<T, K>>;
    demand<K extends string>(key: K | readonly K[], msg?: string | true): Argv<T & {
        [key in K]: unknown;
    }>;
    demand(key: string | readonly string[], required?: boolean): Argv<T>;
    demand(positionals: number, msg: string): Argv<T>;
    demand(positionals: number, required?: boolean): Argv<T>;
    demand(positionals: number, max: number, msg?: string): Argv<T>;
    /**
     * @param key If is a string, show the usage information and exit if key wasn't specified in `process.argv`.
     * If is an array, demand each element.
     * @param msg If string is given, it will be printed when the argument is missing, instead of the standard error message.
     * @param demand Controls whether the option is demanded; this is useful when using .options() to specify command line parameters.
     */
    demandOption<K extends keyof T>(key: K | readonly K[], msg?: string | true): Argv<Defined<T, K>>;
    demandOption<K extends string>(key: K | readonly K[], msg?: string | true): Argv<T & {
        [key in K]: unknown;
    }>;
    demandOption(key: string | readonly string[], demand?: boolean): Argv<T>;
    /**
     * Demand in context of commands.
     * You can demand a minimum and a maximum number a user can have within your program, as well as provide corresponding error messages if either of the demands is not met.
     */
    demandCommand(): Argv<T>;
    demandCommand(min: number, minMsg?: string): Argv<T>;
    demandCommand(min: number, max?: number, minMsg?: string, maxMsg?: string): Argv<T>;
    /**
     * Shows a [deprecated] notice in front of the option
     */
    deprecateOption(option: string, msg?: string): Argv<T>;
    /**
     * Describe a `key` for the generated usage information.
     */
    describe(key: string | readonly string[], description: string): Argv<T>;
    describe(descriptions: {
        [key: string]: string;
    }): Argv<T>;
    /** Should yargs attempt to detect the os' locale? Defaults to `true`. */
    detectLocale(detect: boolean): Argv<T>;
    /**
     * Tell yargs to parse environment variables matching the given prefix and apply them to argv as though they were command line arguments.
     */
    env(): Argv<T>;
    env(prefix: string): Argv<T>;
    env(enable: boolean): Argv<T>;
    /** A message to print at the end of the usage instructions */
    epilog(msg: string): Argv<T>;
    /** A message to print at the end of the usage instructions */
    epilogue(msg: string): Argv<T>;
    /**
     * Give some example invocations of your program.
     * Inside `cmd`, the string `$0` will get interpolated to the current script name or node command for the present script similar to how `$0` works in bash or perl.
     * Examples will be printed out as part of the help message.
     */
    example(command: string, description: string): Argv<T>;
    example(command: ReadonlyArray<[string, string?]>): Argv<T>;
    /** Manually indicate that the program should exit, and provide context about why we wanted to exit. Follows the behavior set by `.exitProcess().` */
    exit(code: number, err: Error): void;
    /**
     * By default, yargs exits the process when the user passes a help flag, the user uses the `.version` functionality, validation fails, or the command handler fails.
     * Calling `.exitProcess(false)` disables this behavior, enabling further actions after yargs have been validated.
     */
    exitProcess(enabled: boolean): Argv<T>;
    /**
     * Method to execute when a failure occurs, rather than printing the failure message.
     * @param func Is called with the failure message that would have been printed, the Error instance originally thrown and yargs state when the failure occurred.
     */
    fail(func: ((msg: string, err: Error, yargs: Argv<T>) => any) | boolean): Argv<T>;
    /**
     * Allows to programmatically get completion choices for any line.
     * @param args An array of the words in the command line to complete.
     * @param done The callback to be called with the resulting completions.
     */
    getCompletion(args: readonly string[], done: (err: Error | null, completions: readonly string[]) => void): Argv<T>;
    getCompletion(args: readonly string[], done?: never): Promise<readonly string[]>;
    /**
     * Returns a promise which resolves to a string containing the help text.
     */
    getHelp(): Promise<string>;
    /**
     * Indicate that an option (or group of options) should not be reset when a command is executed
     */
    global(key: string | readonly string[]): Argv<T>;
    /** Given a key, or an array of keys, places options under an alternative heading when displaying usage instructions */
    group(key: string | readonly string[], groupName: string): Argv<T>;
    /** Hides a key from the generated usage information. Unless a `--show-hidden` option is also passed with `--help` (see `showHidden()`). */
    hide(key: string): Argv<T>;
    /**
     * Configure an (e.g. `--help`) and implicit command that displays the usage string and exits the process.
     * By default yargs enables help on the `--help` option.
     * @param [description] Customizes the description of the help option in the usage string.
     * @param [enableExplicit] If `false` is provided, it will disable --help.
     */
    help(): Argv<T>;
    help(enableExplicit: boolean): Argv<T>;
    help(option: string, enableExplicit: boolean): Argv<T>;
    help(option: string, description?: string, enableExplicit?: boolean): Argv<T>;
    /**
     * Given the key `x` is set, it is required that the key `y` is set.
     * y` can either be the name of an argument to imply, a number indicating the position of an argument or an array of multiple implications to associate with `x`.
     */
    implies(key: string, value: string | readonly string[]): Argv<T>;
    implies(implies: {
        [key: string]: string | readonly string[];
    }): Argv<T>;
    /**
     * Return the locale that yargs is currently using.
     */
    locale(): string;
    /**
     * Override the auto-detected locale from the user's operating system with a static locale.
     * Note that the OS locale can be modified by setting/exporting the `LC_ALL` environment variable.
     */
    locale(loc: string): Argv<T>;
    /**
     * Define global middleware functions to be called first, in list order, for all cli command.
     * @param callbacks Can be a function or a list of functions. Each callback gets passed a reference to argv.
     * @param [applyBeforeValidation] Set to `true` to apply middleware before validation. This will execute the middleware prior to validation checks, but after parsing.
     */
    middleware(callbacks: MiddlewareFunction<T> | ReadonlyArray<MiddlewareFunction<T>>, applyBeforeValidation?: boolean): Argv<T>;
    /**
     * The number of arguments that should be consumed after a key. This can be a useful hint to prevent parsing ambiguity.
     */
    nargs(key: string, count: number): Argv<T>;
    nargs(nargs: {
        [key: string]: number;
    }): Argv<T>;
    /** The key provided represents a path and should have `path.normalize()` applied. */
    normalize<K extends keyof T>(key: K | readonly K[]): Argv<Omit<T, K> & {
        [key in K]: ToString<T[key]>;
    }>;
    normalize<K extends string>(key: K | readonly K[]): Argv<T & {
        [key in K]: string | undefined;
    }>;
    /**
     * Tell the parser to always interpret key as a number.
     */
    number<K extends keyof T>(key: K | readonly K[]): Argv<Omit<T, K> & {
        [key in K]: ToNumber<T[key]>;
    }>;
    number<K extends string>(key: K | readonly K[]): Argv<T & {
        [key in K]: number | undefined;
    }>;
    /**
     * This method can be used to make yargs aware of options that could exist.
     * You can also pass an opt object which can hold further customization, like `.alias()`, `.demandOption()` etc. for that option.
     */
    option<K extends keyof T, O extends Options>(key: K, options: O): Argv<Omit<T, K> & {
        [key in K]: InferredOptionType<O>;
    } & Alias<O>>;
    option<K extends string, O extends Options>(key: K, options: O): Argv<T & {
        [key in K]: InferredOptionType<O>;
    } & Alias<O>>;
    option<O extends {
        [key: string]: Options;
    }>(options: O): Argv<Omit<T, keyof O> & InferredOptionTypes<O> & Alias<O>>;
    /**
     * This method can be used to make yargs aware of options that could exist.
     * You can also pass an opt object which can hold further customization, like `.alias()`, `.demandOption()` etc. for that option.
     */
    options<K extends keyof T, O extends Options>(key: K, options: O): Argv<Omit<T, K> & {
        [key in K]: InferredOptionType<O>;
    }>;
    options<K extends string, O extends Options>(key: K, options: O): Argv<T & {
        [key in K]: InferredOptionType<O>;
    }>;
    options<O extends {
        [key: string]: Options;
    }>(options: O): Argv<Omit<T, keyof O> & InferredOptionTypes<O>>;
    /**
     * Parse `args` instead of `process.argv`. Returns the `argv` object. `args` may either be a pre-processed argv array, or a raw argument string.
     * @param [context]  Provides a useful mechanism for passing state information to commands
     */
    parse(): {
        [key in keyof Arguments<T> as key | CamelCaseKey<key>]: Arguments<T>[key];
    } | Promise<{
        [key in keyof Arguments<T> as key | CamelCaseKey<key>]: Arguments<T>[key];
    }>;
    parse(arg: string | readonly string[], context?: object, parseCallback?: ParseCallback<T>): {
        [key in keyof Arguments<T> as key | CamelCaseKey<key>]: Arguments<T>[key];
    } | Promise<{
        [key in keyof Arguments<T> as key | CamelCaseKey<key>]: Arguments<T>[key];
    }>;
    parseSync(): {
        [key in keyof Arguments<T> as key | CamelCaseKey<key>]: Arguments<T>[key];
    };
    parseSync(arg: string | readonly string[], context?: object, parseCallback?: ParseCallback<T>): {
        [key in keyof Arguments<T> as key | CamelCaseKey<key>]: Arguments<T>[key];
    };
    parseAsync(): Promise<{
        [key in keyof Arguments<T> as key | CamelCaseKey<key>]: Arguments<T>[key];
    }>;
    parseAsync(arg: string | readonly string[], context?: object, parseCallback?: ParseCallback<T>): Promise<{
        [key in keyof Arguments<T> as key | CamelCaseKey<key>]: Arguments<T>[key];
    }>;
    /**
     * If the arguments have not been parsed, this property is `false`.
     */
    parsed: DetailedArguments | false;
    /** Allows to configure advanced yargs features. */
    parserConfiguration(configuration: Partial<ParserConfigurationOptions>): Argv<T>;
    /**
     * Similar to `config()`, indicates that yargs should interpret the object from the specified key in package.json as a configuration object.
     * @param [cwd] If provided, the package.json will be read from this location
     */
    pkgConf(key: string | readonly string[], cwd?: string): Argv<T>;
    /**
     * Allows you to configure a command's positional arguments with an API similar to `.option()`.
     * `.positional()` should be called in a command's builder function, and is not available on the top-level yargs instance. If so, it will throw an error.
     */
    positional<K extends keyof T, O extends PositionalOptions>(key: K, opt: O): Argv<Omit<T, K> & {
        [key in K]: InferredOptionType<O>;
    }>;
    positional<K extends string, O extends PositionalOptions>(key: K, opt: O): Argv<T & {
        [key in K]: InferredOptionType<O>;
    }>;
    /** Should yargs provide suggestions regarding similar commands if no matching command is found? */
    recommendCommands(): Argv<T>;
    /**
     * @deprecated since version 6.6.0
     * Use '.demandCommand()' or '.demandOption()' instead
     */
    require<K extends keyof T>(key: K | readonly K[], msg?: string | true): Argv<Defined<T, K>>;
    require(key: string, msg: string): Argv<T>;
    require(key: string, required: boolean): Argv<T>;
    require(keys: readonly number[], msg: string): Argv<T>;
    require(keys: readonly number[], required: boolean): Argv<T>;
    require(positionals: number, required: boolean): Argv<T>;
    require(positionals: number, msg: string): Argv<T>;
    /**
     * @deprecated since version 6.6.0
     * Use '.demandCommand()' or '.demandOption()' instead
     */
    required<K extends keyof T>(key: K | readonly K[], msg?: string | true): Argv<Defined<T, K>>;
    required(key: string, msg: string): Argv<T>;
    required(key: string, required: boolean): Argv<T>;
    required(keys: readonly number[], msg: string): Argv<T>;
    required(keys: readonly number[], required: boolean): Argv<T>;
    required(positionals: number, required: boolean): Argv<T>;
    required(positionals: number, msg: string): Argv<T>;
    requiresArg(key: string | readonly string[]): Argv<T>;
    /** Set the name of your script ($0). Default is the base filename executed by node (`process.argv[1]`) */
    scriptName($0: string): Argv<T>;
    /**
     * Generate a bash completion script.
     * Users of your application can install this script in their `.bashrc`, and yargs will provide completion shortcuts for commands and options.
     */
    showCompletionScript(): Argv<T>;
    /**
     * Configure the `--show-hidden` option that displays the hidden keys (see `hide()`).
     * @param option If `boolean`, it enables/disables this option altogether. i.e. hidden keys will be permanently hidden if first argument is `false`.
     * If `string` it changes the key name ("--show-hidden").
     * @param description Changes the default description ("Show hidden options")
     */
    showHidden(option?: string | boolean): Argv<T>;
    showHidden(option: string, description?: string): Argv<T>;
    /**
     * Print the usage data using the console function consoleLevel for printing.
     * @param [consoleLevel='error']
     */
    showHelp(consoleLevel?: string): Argv<T>;
    /**
     * Provide the usage data as a string.
     * @param printCallback a function with a single argument.
     */
    showHelp(printCallback: (s: string) => void): Argv<T>;
    /**
     * By default, yargs outputs a usage string if any error is detected.
     * Use the `.showHelpOnFail()` method to customize this behavior.
     * @param enable If `false`, the usage string is not output.
     * @param [message] Message that is output after the error message.
     */
    showHelpOnFail(enable: boolean, message?: string): Argv<T>;
    /**
     * Print the version data using the console function consoleLevel or the specified function.
     * @param [level='error']
     */
    showVersion(level?: 'error' | 'log' | ((message: string) => void)): Argv<T>;
    /** Specifies either a single option key (string), or an array of options. If any of the options is present, yargs validation is skipped. */
    skipValidation(key: string | readonly string[]): Argv<T>;
    /**
     * Any command-line argument given that is not demanded, or does not have a corresponding description, will be reported as an error.
     */
    strict(): Argv<T>;
    strict(enabled: boolean): Argv<T>;
    /**
     * Similar to .strict(), except that it only applies to unrecognized commands.
     * A user can still provide arbitrary options, but unknown positional commands
     * will raise an error.
     */
    strictCommands(): Argv<T>;
    strictCommands(enabled: boolean): Argv<T>;
    /**
     * Similar to `.strict()`, except that it only applies to unrecognized options. A
     * user can still provide arbitrary positional options, but unknown options
     * will raise an error.
     */
    strictOptions(): Argv<T>;
    strictOptions(enabled: boolean): Argv<T>;
    /**
     * Tell the parser logic not to interpret `key` as a number or boolean. This can be useful if you need to preserve leading zeros in an input.
     */
    string<K extends keyof T>(key: K | readonly K[]): Argv<Omit<T, K> & {
        [key in K]: ToString<T[key]>;
    }>;
    string<K extends string>(key: K | readonly K[]): Argv<T & {
        [key in K]: string | undefined;
    }>;
    terminalWidth(): number;
    updateLocale(obj: {
        [key: string]: string;
    }): Argv<T>;
    /**
     * Override the default strings used by yargs with the key/value pairs provided in obj
     */
    updateStrings(obj: {
        [key: string]: string;
    }): Argv<T>;
    /**
     * Set a usage message to show which commands to use.
     * Inside `message`, the string `$0` will get interpolated to the current script name or node command for the present script similar to how `$0` works in bash or perl.
     */
    usage(message: string): Argv<T>;
    usage<U>(command: string | readonly string[], description: string, builder?: (args: Argv<T>) => Argv<U>, handler?: (args: ArgumentsCamelCase<U>) => unknown): Argv<T>;
    usage<U>(command: string | readonly string[], showInHelp: boolean, builder?: (args: Argv<T>) => Argv<U>, handler?: (args: ArgumentsCamelCase<U>) => unknown): Argv<T>;
    usage<O extends {
        [key: string]: Options;
    }>(command: string | readonly string[], description: string, builder?: O, handler?: (args: ArgumentsCamelCase<InferredOptionTypes<O>>) => unknown): Argv<T>;
    usage<O extends {
        [key: string]: Options;
    }>(command: string | readonly string[], showInHelp: boolean, builder?: O, handler?: (args: ArgumentsCamelCase<InferredOptionTypes<O>>) => unknown): Argv<T>;
    /**
     * Add an option (e.g. `--version`) that displays the version number (given by the version parameter) and exits the process.
     * By default yargs enables version for the `--version` option.
     */
    version(): Argv<T>;
    version(version: string): Argv<T>;
    version(enable: boolean): Argv<T>;
    version(optionKey: string, version: string): Argv<T>;
    version(optionKey: string, description: string, version: string): Argv<T>;
    /**
     * Format usage output to wrap at columns many columns.
     */
    wrap(columns: number | null): Argv<T>;
    /** burgee: the manifest every surface — help, `--json`, `--schema`, `--mcp`, completions — is projected from (J7, J8). */
    readonly manifest: Manifest;
    /** burgee: declare what the command does to the world (N6); what exposes it as an MCP tool (N2). */
    effects(value: DeclaredEffects): Argv<T>;
    /** burgee: plugins yargs never had. `preRun`/`postRun` fire around every handler. */
    use(plugin: Plugin): Argv<T>;
    /** burgee: inject the streams and the exit for this instance (T1), and get E1 exit codes back. */
    burgee(seam: BurgeeSeam): Argv<T>;
}
```

### CommandModule

```ts
interface CommandModule<T = {}, U = {}> {
    /** array of strings (or a single string) representing aliases of `exports.command`, positional args defined in an alias are ignored */
    aliases?: readonly string[] | string | undefined;
    /** object declaring the options the command accepts, or a function accepting and returning a yargs instance */
    builder?: CommandBuilder<T, U> | undefined;
    /** string (or array of strings) that executes this command when given on the command line, first string may contain positional args */
    command?: readonly string[] | string | undefined;
    /** boolean (or string) to show deprecation notice */
    deprecated?: boolean | string | undefined;
    /** string used as the description for the command in help text, use `false` for a hidden command */
    describe?: string | false | undefined;
    /** a function which will be passed the parsed argv. */
    handler: (args: ArgumentsCamelCase<U>) => unknown;
}
```

### DetailedArguments

```ts
interface DetailedArguments {
    argv: Record<string, any>;
    error: Error | null;
    aliases: Record<string, string[]>;
    newAliases: Record<string, boolean>;
    defaulted: Record<string, boolean>;
    configuration: Record<string, any>;
}
```

### Options

```ts
interface Options {
    /** string or array of strings, alias(es) for the canonical option key, see `alias()` */
    alias?: string | readonly string[] | undefined;
    /** boolean, interpret option as an array, see `array()` */
    array?: boolean | undefined;
    /**  boolean, interpret option as a boolean flag, see `boolean()` */
    boolean?: boolean | undefined;
    /** value or array of values, limit valid option arguments to a predefined set, see `choices()` */
    choices?: Choices | undefined;
    /** function, coerce or transform parsed command line values into another value, see `coerce()` */
    coerce?: ((arg: any) => any) | undefined;
    /** boolean, interpret option as a path to a JSON config file, see `config()` */
    config?: boolean | undefined;
    /** function, provide a custom config parsing function, see `config()` */
    configParser?: ((configPath: string) => object) | undefined;
    /** string or object, require certain keys not to be set, see `conflicts()` */
    conflicts?: string | readonly string[] | {
        [key: string]: string | readonly string[];
    } | undefined;
    /** boolean, interpret option as a count of boolean flags, see `count()` */
    count?: boolean | undefined;
    /** value, set a default value for the option, see `default()` */
    default?: any;
    /** string, use this description for the default value in help content, see `default()` */
    defaultDescription?: string | undefined;
    /**
     *  @deprecated since version 6.6.0
     *  Use 'demandOption' instead
     */
    demand?: boolean | string | undefined;
    /** boolean or string, mark the argument as deprecated, see `deprecateOption()` */
    deprecate?: boolean | string | undefined;
    /** boolean or string, mark the argument as deprecated, see `deprecateOption()` */
    deprecated?: boolean | string | undefined;
    /** boolean or string, demand the option be given, with optional error message, see `demandOption()` */
    demandOption?: boolean | string | undefined;
    /** string, the option description for help content, see `describe()` */
    desc?: string | undefined;
    /** string, the option description for help content, see `describe()` */
    describe?: string | undefined;
    /** string, the option description for help content, see `describe()` */
    description?: string | undefined;
    /** boolean, indicate that this key should not be reset when a command is invoked, see `global()` */
    global?: boolean | undefined;
    /** string, when displaying usage instructions place the option under an alternative group heading, see `group()` */
    group?: string | undefined;
    /** don't display option in help output. */
    hidden?: boolean | undefined;
    /**  string or object, require certain keys to be set, see `implies()` */
    implies?: string | readonly string[] | {
        [key: string]: string | readonly string[];
    } | undefined;
    /** number, specify how many arguments should be consumed for the option, see `nargs()` */
    nargs?: number | undefined;
    /** boolean, apply path.normalize() to the option, see `normalize()` */
    normalize?: boolean | undefined;
    /** boolean, interpret option as a number, `number()` */
    number?: boolean | undefined;
    /**
     *  @deprecated since version 6.6.0
     *  Use 'demandOption' instead
     */
    require?: boolean | string | undefined;
    /**
     *  @deprecated since version 6.6.0
     *  Use 'demandOption' instead
     */
    required?: boolean | string | undefined;
    /** boolean, require the option be specified with a value, see `requiresArg()` */
    requiresArg?: boolean | undefined;
    /** boolean, skips validation if the option is present, see `skipValidation()` */
    skipValidation?: boolean | undefined;
    /** boolean, interpret option as a string, see `string()` */
    string?: boolean | undefined;
    type?: 'array' | 'count' | PositionalOptionsType | undefined;
}
```

### ParsedCommand

```ts
interface ParsedCommand {
    cmd: string;
    demanded: Positional[];
    optional: Positional[];
}
```

### Parser

```ts
interface Parser {
    (args: string | any[], opts?: any): Record<string, any>;
    detailed: (args: string | any[], opts?: any) => DetailedArguments;
    camelCase: typeof camelCase;
    decamelize: typeof decamelize;
    looksLikeNumber: typeof looksLikeNumber;
}
```

### PlatformShim

```ts
interface PlatformShim {
    assert: {
        notStrictEqual: (a: any, b: any, m?: string) => void;
        strictEqual: (a: any, b: any, m?: string) => void;
    };
    cliui: typeof cliui;
    findUp: (start: string, callback: (dir: string, names: string[]) => string | undefined) => string | undefined;
    getEnv: (key: string) => string | undefined;
    inspect: typeof inspect;
    getProcessArgvBin: () => string;
    mainFilename: string;
    Parser: typeof Parser;
    path: {
        basename: typeof basename;
        dirname: typeof dirname;
        extname: typeof extname;
        relative: typeof relative;
        resolve: typeof resolve;
        join: typeof join;
    };
    process: {
        argv: () => string[];
        cwd: () => string;
        emitWarning: (warning: string | Error, type?: string) => void;
        execPath: () => string;
        exit: (code: number) => void;
        nextTick: (cb: () => void) => void;
        stdColumns: number | null;
        /** burgee: the streams --mcp serves on, reached through the shim like everything else. */
        stdin: () => NodeJS.ReadableStream;
        stdout: () => {
            write: (s: string) => unknown;
        };
    };
    readFileSync: typeof readFileSync;
    readdirSync: typeof readdirSync;
    require: NodeJS.Require;
    getCallerFile: () => string;
    stringWidth: (str: string) => number;
    y18n: Y18N;
    /** burgee: a previous major's command collaborator, where its behaviour differs from 18's (`yargs/v17-factory.ts`). */
    CommandInstance?: typeof CommandInstance;
}
```

### PositionalOptions

```ts
interface PositionalOptions {
    /** string or array of strings, see `alias()` */
    alias?: string | readonly string[] | undefined;
    /** boolean, interpret option as an array, see `array()` */
    array?: boolean | undefined;
    /** value or array of values, limit valid option arguments to a predefined set, see `choices()` */
    choices?: Choices | undefined;
    /** function, coerce or transform parsed command line values into another value, see `coerce()` */
    coerce?: ((arg: any) => any) | undefined;
    /** string or object, require certain keys not to be set, see `conflicts()` */
    conflicts?: string | readonly string[] | {
        [key: string]: string | readonly string[];
    } | undefined;
    /** value, set a default value for the option, see `default()` */
    default?: any;
    /** boolean or string, demand the option be given, with optional error message, see `demandOption()` */
    demandOption?: boolean | string | undefined;
    /** string, the option description for help content, see `describe()` */
    desc?: string | undefined;
    /** string, the option description for help content, see `describe()` */
    describe?: string | undefined;
    /** string, the option description for help content, see `describe()` */
    description?: string | undefined;
    /** string or object, require certain keys to be set, see `implies()` */
    implies?: string | readonly string[] | {
        [key: string]: string | readonly string[];
    } | undefined;
    /** boolean, apply path.normalize() to the option, see normalize() */
    normalize?: boolean | undefined;
    type?: PositionalOptionsType | undefined;
}
```

### RequireDirectoryOptions

```ts
interface RequireDirectoryOptions {
    /** Look for command modules in all subdirectories and apply them as a flattened (non-hierarchical) list. */
    recurse?: boolean | undefined;
    /** The types of files to look for when requiring command modules. */
    extensions?: readonly string[] | undefined;
    /**
     * A synchronous function called for each command module encountered.
     * Accepts `commandObject`, `pathToFile`, and `filename` as arguments.
     * Returns `commandObject` to include the command; any falsy value to exclude/skip it.
     */
    visit?: ((commandObject: any, pathToFile?: string, filename?: string) => any) | undefined;
    /** Whitelist certain modules */
    include?: RegExp | ((pathToFile: string) => boolean) | undefined;
    /** Blacklist certain modules. */
    exclude?: RegExp | ((pathToFile: string) => boolean) | undefined;
}
```

## Types

### Arguments

```ts
type Arguments<T = {}> = T & {
    /** Non-option arguments */
    _: Array<string | number>;
    /** The script name or node command */
    $0: string;
    /** All remaining options */
    [argName: string]: unknown;
};
```

### ArgumentsCamelCase

Arguments type, with camelcased keys

```ts
type ArgumentsCamelCase<T = {}> = {
    [key in keyof T as key | CamelCaseKey<key>]: T[key];
} & {
    /** Non-option arguments */
    _: Array<string | number>;
    /** The script name or node command */
    $0: string;
    /** All remaining options */
    [argName: string]: unknown;
};
```

### AsyncCompletionFunction

```ts
type AsyncCompletionFunction = (current: string, argv: any, done: (completion: readonly string[]) => void) => void;
```

### BuilderArguments

```ts
type BuilderArguments<T extends (...args: any) => R, R = ReturnType<T>> = R extends Argv<infer X> ? ArgumentsCamelCase<X> : {} | R extends PromiseLike<Argv<infer X>> ? ArgumentsCamelCase<X> : {};
```

### BuilderCallback

```ts
type BuilderCallback<T, R> = ((args: Argv<T>) => PromiseLike<Argv<R>>) | ((args: Argv<T>) => Argv<R>) | ((args: Argv<T>) => void);
```

### Choices

```ts
type Choices = ReadonlyArray<string | number | true | undefined>;
```

### CommandBuilder

```ts
type CommandBuilder<T = {}, U = {}> = {
    [key: string]: Options;
} | ((args: Argv<T>) => Argv<U>) | ((args: Argv<T>) => PromiseLike<Argv<U>>);
```

### CompletionCallback

```ts
type CompletionCallback = (err: Error | null, completions: string[] | undefined) => void;
```

### Defined

Remove undefined as a possible value for keys K in T

```ts
type Defined<T, K extends keyof T> = Omit<T, K> & {
    [key in K]: Exclude<T[key], undefined>;
};
```

### FallbackCompletionFunction

```ts
type FallbackCompletionFunction = (current: string, argv: any, completionFilter: (onCompleted?: CompletionCallback) => any, done: (completions: string[]) => any) => void;
```

### InferredOptionType

```ts
type InferredOptionType<O extends Options | PositionalOptions> = O extends ({
    coerce: (arg: any) => infer T;
}) ? IsRequiredOrHasDefault<O> extends true ? T : T | undefined : O extends ({
    type: 'count';
    default: infer D;
} | {
    count: true;
    default: infer D;
}) ? number | Exclude<D, undefined> : O extends ({
    type: 'count';
} | {
    count: true;
}) ? number : IsUnknown<InferredOptionTypePrimitive<O>> extends false ? InferredOptionTypePrimitive<O> : O extends ({
    default: infer D;
}) ? Exclude<D, undefined> : unknown;
```

### InferredOptionTypeInner

```ts
type InferredOptionTypeInner<O extends Options | PositionalOptions> = O extends {
    type: 'array';
    choices: ReadonlyArray<infer C>;
} ? C[] : O extends {
    type: 'array';
    string: true;
} ? string[] : O extends {
    type: 'array';
    number: true;
} ? number[] : O extends {
    type: 'array';
    normalize: true;
} ? string[] : O extends {
    array: true;
    choices: ReadonlyArray<infer C>;
} ? C[] : O extends {
    array: true;
    type: 'string';
} ? string[] : O extends {
    array: true;
    type: 'number';
} ? number[] : O extends {
    array: true;
    string: true;
} ? string[] : O extends {
    array: true;
    number: true;
} ? number[] : O extends {
    array: true;
    normalize: true;
} ? string[] : O extends {
    choices: ReadonlyArray<infer C>;
} ? C : O extends {
    type: 'array';
} ? Array<string | number> : O extends {
    type: 'boolean';
} ? boolean : O extends {
    type: 'number';
} ? number : O extends {
    type: 'string';
} ? string : O extends {
    array: true;
} ? Array<string | number> : O extends {
    boolean: true;
} ? boolean : O extends {
    number: true;
} ? number : O extends {
    string: true;
} ? string : O extends {
    normalize: true;
} ? string : unknown;
```

### InferredOptionTypePrimitive

```ts
type InferredOptionTypePrimitive<O extends Options | PositionalOptions> = O extends {
    default: infer D;
} ? IsRequiredOrHasDefault<O> extends true ? InferredOptionTypeInner<O> | Exclude<D, undefined> : InferredOptionTypeInner<O> | D : IsRequiredOrHasDefault<O> extends true ? InferredOptionTypeInner<O> : InferredOptionTypeInner<O> | undefined;
```

### InferredOptionTypes

```ts
type InferredOptionTypes<O extends {
    [key: string]: Options;
}> = {
    [key in keyof O]: InferredOptionType<O[key]>;
};
```

### MiddlewareFunction

```ts
type MiddlewareFunction<T = {}> = (args: ArgumentsCamelCase<T>) => void | Promise<void>;
```

### ParseCallback

```ts
type ParseCallback<T = {}> = (err: Error | undefined, argv: ArgumentsCamelCase<T>, output: string) => void | Promise<void>;
```

### ParserConfigurationOptions

```ts
type ParserConfigurationOptions = Configuration & {
    /** Sort commands alphabetically. Default is `false` */
    'sort-commands': boolean;
};
```

### PositionalOptionsType

```ts
type PositionalOptionsType = 'boolean' | 'number' | 'string';
```

### PromiseCompletionFunction

```ts
type PromiseCompletionFunction = (current: string, argv: any) => Promise<string[]>;
```

### SyncCompletionFunction

```ts
type SyncCompletionFunction = (current: string, argv: any) => string[];
```

### ToArray

Convert T to T[] and T | undefined to T[] | undefined

```ts
type ToArray<T> = Array<Exclude<T, undefined>> | Extract<T, undefined>;
```

### ToNumber

Gives number[] if T is an array type, otherwise number. Preserves | undefined.

```ts
type ToNumber<T> = (Exclude<T, undefined> extends any[] ? number[] : number) | Extract<T, undefined>;
```

### ToString

Gives string[] if T is an array type, otherwise string. Preserves | undefined.

```ts
type ToString<T> = (Exclude<T, undefined> extends any[] ? string[] : string) | Extract<T, undefined>;
```

---

# burgee/yargs/v17/yargs

> Every export of burgee/yargs/v17/yargs, with its signature and doc comment: module.exports, factory.

Source: https://burgee.interlace.tools/docs/api/yargs/v17/yargs

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

`burgee/yargs/v17/yargs` — yargs 17's `yargs/yargs`: the factory, never the singleton, with
the three statics 17 hangs on it (`applyExtends`, `hideBin`, `Parser`). The form 17's README
teaches for CommonJS, `require('yargs/yargs')(hideBin(process.argv))`, and `burgee migrate`
writes this entry for it (`previous-majors` R3, R6).

```ts
import factory from 'burgee/yargs/v17/yargs';
import { module.exports } from 'burgee/yargs/v17/yargs';
```

## Constants

### default

The default export, declared as `factory`.

```ts
const factory: ((processArgs?: string | readonly string[] | undefined, cwd?: string | undefined, parentRequire?: NodeJS.Require | undefined) => import("./types.js").Argv<{}>) & {
    applyExtends: typeof applyExtends;
    hideBin: typeof hideBin;
    Parser: Parser;
};
```

### module.exports

```ts
const factory: ((processArgs?: string | readonly string[] | undefined, cwd?: string | undefined, parentRequire?: NodeJS.Require | undefined) => import("./types.js").Argv<{}>) & {
    applyExtends: typeof applyExtends;
    hideBin: typeof hideBin;
    Parser: Parser;
};
```

---

# Benchmarks

> Every number this project claims in public, measured — and the ones that are not measured, saying so.

Source: https://burgee.interlace.tools/docs/benchmarks

Generated by `npm run bench:page` from the run of 2026-10-19 at commit `66e4611`.
Do not edit by hand.

## Published claims, settled

Every number this repository states in public, checked against the record that settles it.
**"Not met" and "unmeasured" are different outcomes** and never collapse into each other:
one says we measured and it is not true, the other says we have not measured.

| Claim | Target | Measured | Outcome |
| :--- | :--- | ---: | :--- |
| the engine's cold start stays within 1.55× of cac's, the lightest framework in the landscape (a downward-only ratchet; the ≤ 1 bar is not reachable, D-102) | `<= 1.55` | 1.473 ratio | ✅ met |
| the core entry point is under 52 KB bundled | `<= 53248` | 24,281 bytes | ✅ met |
| `burgee` stays within 2.35× of `cac` alone in a user's bundle (a downward-only ratchet, lowered as it shrinks; ≤ 1 is not reachable, D-102) | `<= 2.35` | 2.323 ratio | ✅ met |
| `burgee/commander` stays within 1.42× of `commander` alone in a user's bundle (a downward-only ratchet, lowered as it shrinks; ≤ 1 is not reachable, D-102) | `<= 1.42` | 1.416 ratio | ✅ met |
| `burgee/yargs` is lighter in a user's bundle than `yargs`, the package it replaces | `<= 1` | 0.97 ratio | ✅ met |
| `roundel/chalk` is lighter in a user's bundle than `chalk`, the package it replaces | `<= 1` | 0.599 ratio | ✅ met |
| `roundel/tokens` is lighter in a user's bundle than `picocolors`, the package it replaces | `<= 1` | 0.15 ratio | ✅ met |
| `flagstaff/ora` is lighter in a user's bundle than `ora`, the package it replaces | `<= 1` | 0.938 ratio | ✅ met |
| `flagstaff/boxen` is lighter in a user's bundle than `boxen`, the package it replaces | `<= 1` | 0.698 ratio | ✅ met |
| `flagstaff/cli-table3` is lighter in a user's bundle than `cli-table3`, the package it replaces | `<= 1` | 0.705 ratio | ✅ met |
| `flagstaff/spinner` is lighter in a user's bundle than `ora`, the package it replaces | `<= 1` | 0.121 ratio | ✅ met |
| `flagstaff/box` is lighter in a user's bundle than `boxen`, the package it replaces | `<= 1` | 0.503 ratio | ✅ met |
| `flagstaff/table` is lighter in a user's bundle than `cli-table3`, the package it replaces | `<= 1` | 0.554 ratio | ✅ met |
| `flagstaff/log-update` is lighter in a user's bundle than `log-update`, the package it replaces | `<= 1` | 0.517 ratio | ✅ met |
| `linegauge` is lighter in a user's bundle than `string-width`, the package it replaces | `<= 1` | 0.939 ratio | ✅ met |
| `linegauge/wrap` is lighter in a user's bundle than `wrap-ansi`, the package it replaces | `<= 1` | 0.795 ratio | ✅ met |
| `linegauge/slice` is lighter in a user's bundle than `slice-ansi`, the package it replaces | `<= 1` | 0.78 ratio | ✅ met |
| `linegauge/strip` is lighter in a user's bundle than `strip-ansi`, the package it replaces | `<= 1` | 0.595 ratio | ✅ met |
| `paratext` is lighter in a user's bundle than `ansi-escapes`, the package it replaces | `<= 1` | 1.632 ratio | ❌ **not met** |
| `bellpull` is lighter in a user's bundle than `tinyexec`, the package it replaces | `<= 1` | 0.986 ratio | ✅ met |
| `seniority/lilconfig` is lighter in a user's bundle than `lilconfig`, the package it replaces | `<= 1` | 0.615 ratio | ✅ met |
| `seniority/dotenv` is lighter in a user's bundle than `dotenv`, the package it replaces | `<= 1` | 0.52 ratio | ✅ met |
| `closeout/exit-hook` is lighter in a user's bundle than `exit-hook`, the package it replaces | `<= 1` | 2.929 ratio | ❌ **not met** |
| `closeout/signal-exit` is lighter in a user's bundle than `signal-exit`, the package it replaces | `<= 1` | 1.272 ratio | ❌ **not met** |
| `controlroom/ink` + `react` + `react-reconciler` is lighter in a user's bundle than `ink` + `react`, what it replaces | `<= 1` | 0.79 ratio | ✅ met |
| `controlroom` is lighter in a user's bundle than `ink`, the package it replaces | `<= 1` | 0.063 ratio | ✅ met |
| `controlroom/ink` + `react` + `react-reconciler` installs no more bytes than `ink` + `react` | `<= 1` | 0.419 ratio | ✅ met |
| `controlroom/ink` + `react` + `react-reconciler` installs no more packages than `ink` + `react` | `<= 1` | 0.25 ratio | ✅ met |
| importing `controlroom/ink` starts no slower than importing `ink` + `react`, as a same-run ratio | `<= 1` | 0.416 ratio | ✅ met |
| importing `controlroom` starts no slower than importing `ink` + `react`, as a same-run ratio | `<= 1` | 0.159 ratio | ✅ met |
| `burgee` is lighter in a user's bundle than `cac` plus the 3 packages a user of it installs to reach the same capability set | `<= 1` | 0.249 ratio | ✅ met |
| `burgee/commander` is lighter in a user's bundle than `commander` plus the 3 packages a user of it installs to reach the same capability set | `<= 1` | 0.438 ratio | ✅ met |
| `burgee/yargs` is lighter in a user's bundle than `yargs` plus the 3 packages a user of it installs to reach the same capability set | `<= 1` | 0.545 ratio | ✅ met |
| commander's own test suite passes 1360 of 1360 against our entry point | `>= 1360` | 1,360 tests | ✅ met |
| yargs's own test suite passes 816 of 816 against our entry point | `>= 816` | 816 tests | ✅ met |
| chalk's own test suite passes 58 of 58 against our entry point | `>= 58` | 59 tests | ✅ met |
| ora's own test suite passes 99 of 99 against our entry point | `>= 99` | 99 tests | ✅ met |
| log-update's own test suite passes 99 of 99 against our entry point | `>= 99` | 99 tests | ✅ met |
| boxen's own test suite passes 84 of 84 against our entry point | `>= 84` | 213 tests | ✅ met |
| an agent spends at least 40% fewer tokens per task against a CLI that meets the floor | `<= 0.6` | 0.747 ratio | ❌ **not met** |
| an agent takes at least 30% fewer turns per task against a CLI that meets the floor | `<= 0.7` | 0.75 ratio | ❌ **not met** |

> **The two agent rows changed measure on 2026-10-09** (D-20261009-b1-totals-and-explain). This run settled
> them on the ratio of pooled medians, which commander's bimodal median turned into a coin flip. They are
> now settled on the tokens and turns each build spends summed over every task-run. Summed from this run's
> per-task detail, burgee ÷ commander is **0.692** for tokens (claim ≤ 0.6) and
> **0.703** for turns (claim ≤ 0.7). The first published run that carries the total
> records settles both rows here.

## B2 — cold start

Spawned processes, not an in-process micro-benchmark: process time is what a user and an
agent actually pay, and excluding Node's own startup would flatter every row.
**`bare node` is the floor row** and most of every other number.

> These milliseconds are a property of the machine that ran them —
> AMD EPYC 7763 64-Core Processor, 4 cores, linux/x64, Node v24.13.0, on CI — and are **not comparable across
> machines**. Nothing gates on them. What is gated and banded is the ratio below, taken
> between two spawns interleaved in the same run, which cancels the machine out.

| Variant | p50 ms | p95 ms | spawns |
| :--- | ---: | ---: | ---: |
| `bare node` | 27.5 | 28.7 | 52 |
| `commander` | 42.8 | 46.7 | 52 |
| `burgee/commander` | 46.5 | 49.6 | 52 |
| `yargs` | 104.6 | 108.0 | 52 |
| `burgee/yargs` | 66.7 | 70.5 | 52 |
| `cac` | 31.6 | 34.0 | 52 |
| `burgee` | 46.6 | 47.7 | 52 |
| `picocolors` | 31.1 | 32.1 | 52 |
| `roundel/tokens` | 31.1 | 32.3 | 52 |
| `roundel/chalk` | 33.7 | 34.9 | 52 |
| `ink + react` | 343.7 | 352.5 | 52 |
| `controlroom/ink` | 142.1 | 158.2 | 52 |
| `controlroom` | 54.5 | 59.3 | 52 |

| Ratio | p50 | p95 | gate |
| :--- | ---: | ---: | ---: |
| burgee/commander ÷ commander | **1.072×** | 1.171× | ≤ 1.4 |
| burgee/yargs ÷ yargs | **0.639×** | 0.672× | ≤ 0.95 |
| burgee ÷ cac | **1.473×** | 1.517× | ≤ 1.55 |
| controlroom/ink ÷ ink + react | **0.416×** | 0.453× | ≤ 1 |
| controlroom ÷ ink + react | **0.159×** | 0.171× | ≤ 1 |

## B1, the half that needs no model — what an agent can act on

Not B1, and not a stand-in for it: this measures nothing about tokens or turns. It measures
whether the CLI's answer is *legible* to an agent, which needs no model at all. Ten tasks
per variant, one spawn each, non-TTY with **stdin closed** — the only environment an agent
gets. The same demo program, built on each engine.

| Variant | hangs/100 | exit code | `--json` | bytes |
| :--- | ---: | ---: | ---: | ---: |
| `burgee` | 0 | 100.0% | 100.0% | 164 |
| `commander` | 0 | 40.0% | 25.0% | 31 |
| `yargs` | 0 | 40.0% | 25.0% | 458 |

**Exit code** is the one that decides an agent's next move: `2` means *rewrite the command*,
any other non-zero means *the command was fine and the world was not*. Both incumbents
answer `1` to a usage error, which tells an agent nothing — so it retries a malformed
command until it gives up.

**Bytes is reported against us and is not gated.** commander reads fewer than we do, because
our errors carry a `hint` naming the fix. That is a trade — bytes per failure against failed
turns — and only B1 proper can settle it. It is on this page precisely so the trade is
visible rather than quietly omitted.

## N10 — the floor, graded by someone else's checklist

Every other number on this page comes from an instrument this repository wrote, and an
instrument its authors wrote can only find the faults they thought of. This one hands the
same demo program to two published, third-party checkers and records what they say:
[clispec](https://clispec.dev) 0.3.0, the scorer for The CLI Spec v0.3 (six principles, 24
points), and [cli-agent-lint](https://github.com/Camil-H/cli-agent-lint) 0.3.5 (34 checks,
graded A–F). Both are pinned by version and archive digest in `benchmarks/floor-tools.ts`,
run offline, and are never re-scored here — a check they fail is listed as failed, even where
we would argue with it.

Measured at commit `28843a5` on 2026-10-19.

| Variant | clispec | cli-agent-lint |
| :--- | ---: | ---: |
| `burgee` | 24 / 24 (Excellent) | 100.0% (A) |
| `commander` | 2 / 24 (Needs Work) | 71.2% (B) |
| `yargs` | 2 / 24 (Needs Work) | 70.9% (B) |

What clispec 0.3.0 failed on burgee's demo:

- none

What cli-agent-lint 0.3.5 did not pass on burgee's demo (`warn` and `info` included; `skip` is not):

- none

## B5 — runtime against the incumbent

"Faster" is a claim like any other, so it is measured like one. One realistic workload per
pair — the mixed text a CLI prints, a redrawn frame, a 20-row wrapped table, a prompt typed into
and submitted — each in its own process, in front of a TTY with colour and hyperlinks forced, and
each first proving that ours and the incumbent print **the same bytes**: a ratio between two
different jobs is the flattering number this page exists to refuse. Eleven interleaved rounds;
the number is the median of the per-round ratio, ours ÷ theirs, so a round's load lands on both.
A reading over its ceiling is confirmed by two more fresh processes before it fails, so load on
one process cannot fail a pull request and a regression in every process still does.

**The target is ≤ 1.0 for every pair.** Where a pair is above it, the gate is a ceiling just above
its CI measurement that **may only go down**: the PR that makes the pair faster lowers it, and
raising one takes a recorded decision (`.sdlc/bands/runtime-ratchets.json`).

Measured at commit `66e4611`:

| Pair | ours ÷ theirs, p50 | p95 | ≤ 1.0 | gate |
| :--- | ---: | ---: | :--- | ---: |
| paratext ÷ ansi-escapes | **1.107×** | 1.138× | ❌ **not met** | ≤ 1.15 |
| paratext/terminal-link ÷ terminal-link | **0.749×** | 0.768× | ✅ met | ≤ 0.95 |
| linegauge ÷ string-width | **0.725×** | 0.743× | ✅ met | ≤ 0.85 |
| linegauge/strip ÷ strip-ansi | **1.007×** | 1.045× | ❌ **not met** | ≤ 1.1 |
| linegauge/wrap ÷ wrap-ansi | **0.736×** | 0.785× | ✅ met | ≤ 0.85 |
| linegauge/slice ÷ slice-ansi | **0.956×** | 1.160× | ✅ met | ≤ 1.05 |
| roundel/chalk ÷ chalk | **1.253×** | 1.281× | ❌ **not met** | ≤ 1.35 |
| bellpull/node-which ÷ which | **0.302×** | 0.341× | ✅ met | ≤ 0.5 |
| bellpull ÷ tinyexec | **0.987×** | 0.999× | ✅ met | ≤ 1 |
| flagstaff/ora ÷ ora | **0.930×** | 1.006× | ✅ met | ≤ 1.05 |
| flagstaff/log-update ÷ log-update | **0.789×** | 1.335× | ✅ met | ≤ 1.05 |
| flagstaff/boxen ÷ boxen | **0.376×** | 0.413× | ✅ met | ≤ 0.45 |
| flagstaff/cli-table3 ÷ cli-table3 | **0.388×** | 0.455× | ✅ met | ≤ 0.45 |
| caique/clack ÷ @clack/prompts | **1.119×** | 1.150× | ❌ **not met** | ≤ 1.7 |
| burgee/commander ÷ commander | **1.071×** | 1.182× | ❌ **not met** | ≤ 1.2 |
| burgee/yargs ÷ yargs | **1.062×** | 1.175× | ❌ **not met** | ≤ 1.1 |

The ceilings every pull request is gated on today:

| Entry point | Replaces | Target | Ceiling | First ceiling | Steps |
| :--- | :--- | :--- | ---: | ---: | ---: |
| `paratext` | `ansi-escapes` | ≤ 1 | **≤ 1.15** | 12.35 (2026-09-29) | 3 |
| `paratext/terminal-link` | `terminal-link` | ≤ 1 | **≤ 0.95** | 29.7 (2026-09-29) | 3 |
| `linegauge` | `string-width` | ≤ 1 | **≤ 0.85** | 1.95 (2026-09-29) | 4 |
| `linegauge/strip` | `strip-ansi` | ≤ 1 | **≤ 1.1** | 5.6 (2026-09-29) | 4 |
| `linegauge/wrap` | `wrap-ansi` | ≤ 1 | **≤ 0.85** | 2.6 (2026-09-29) | 4 |
| `linegauge/slice` | `slice-ansi` | ≤ 1 | **≤ 1.05** | 11.65 (2026-09-29) | 4 |
| `roundel/chalk` | `chalk` | ≤ 1 | **≤ 1.35** | 5.5 (2026-09-29) | 4 |
| `bellpull/node-which` | `which` | ≤ 1 | **≤ 0.5** | 1.8 (2026-09-29) | 3 |
| `bellpull` | `tinyexec` | ≤ 1 | **≤ 1** | 1 (2026-09-30) | 1 |
| `flagstaff/ora` | `ora` | ≤ 1 | **≤ 1.05** | 1.8 (2026-09-29) | 5 |
| `flagstaff/log-update` | `log-update` | ≤ 1 | **≤ 1.05** | 4.2 (2026-09-29) | 4 |
| `flagstaff/boxen` | `boxen` | ≤ 1 | **≤ 0.45** | 1.3 (2026-09-29) | 5 |
| `flagstaff/cli-table3` | `cli-table3` | ≤ 1 | **≤ 0.45** | 2.2 (2026-09-29) | 4 |
| `caique/clack` | `@clack/prompts` | ≤ 1 | **≤ 1.7** | 3.35 (2026-09-29) | 4 |
| `burgee/commander` | `commander` | ≤ 1 | **≤ 1.2** | 1.6 (2026-09-29) | 3 |
| `burgee/yargs` | `yargs` | ≤ 1 | **≤ 1.1** | 1.55 (2026-09-29) | 3 |

## B3 — compatibility

Read from `compat-oracle` and never recomputed here: two implementations of a
compatibility rate produce two rates. The full method, and the control column that proves
the gate works, are on [Compatibility](/docs/compatibility).

| Host | Passing | Rate |
| :--- | ---: | ---: |
| **ansi-escapes** | 4 | 100.0% |
| **boxen** | 213 | 100.0% |
| **chalk** | 59 | 100.0% |
| **clack** | 16 | 100.0% |
| **cli-cursor** | 8 | 100.0% |
| **cli-table3** | 29 | 100.0% |
| **cli-truncate** | 12 | 100.0% |
| **commander** | 1,360 | 100.0% |
| **cosmiconfig** | 242 | 99.6% |
| **cross-spawn** | 68 | 100.0% |
| **dotenv** | 193 | 100.0% |
| **execa** | 0 | 0.0% |
| **exit-hook** | 21 | 100.0% |
| **extra-typings** | 369 | 100.0% |
| **find-up** | 104 | 100.0% |
| **ink** | 1,304 | 100.0% |
| **inkjs-ui** | 102 | 100.0% |
| **inquirer-core** | 41 | 100.0% |
| **inquirer-prompts** | 100 | 46.9% |
| **lilconfig** | 77 | 100.0% |
| **log-update** | 99 | 100.0% |
| **meow** | 146 | 98.6% |
| **onetime** | 6 | 100.0% |
| **ora** | 99 | 100.0% |
| **picocolors** | 1 | 100.0% |
| **rc** | 1 | 100.0% |
| **restore-cursor** | 6 | 100.0% |
| **signal-exit** | 134 | 99.3% |
| **slice-ansi** | 104 | 100.0% |
| **string-width** | 233 | 100.0% |
| **strip-ansi** | 8 | 100.0% |
| **term-img** | 18 | 100.0% |
| **terminal-link** | 8 | 100.0% |
| **which** | 5 | 100.0% |
| **widest-line** | 1 | 100.0% |
| **wrap-ansi** | 85 | 100.0% |
| **yargs** | 816 | 100.0% |

## B4 — weight

**Bundled** is what your application grows by when you import that entry point: a fixture
importing exactly it, one symbol used, esbuild-minified — the incumbent measured by the
same command over the same fixture shape. A tarball size answers a different question.

**Installed** is what `npm install` puts on disk, including everything the package drags
in. Ours drag nothing, which is where the two columns diverge most; but one of our packages
serves every entry point it publishes, so the installed column is not per-entry-point and
nothing gates on it.

| Entry point | Replaces | Bundled | Theirs | Ratio | Installed | Theirs |
| :--- | :--- | ---: | ---: | ---: | ---: | ---: |
| `burgee` | `cac` | 24,281 | 10,452 | **2.323×** | 1,721,458 | 41,198 |
| `burgee/commander` | `commander` | 55,351 | 39,084 | **1.416×** | 1,721,458 | 207,368 |
| `burgee/yargs` | `yargs` | 108,350 | 111,686 | **0.970×** | 1,721,458 | 528,744 |
| `roundel/chalk` | `chalk` | 4,790 | 8,002 | **0.599×** | 113,948 | 56,180 |
| `roundel/tokens` | `picocolors` | 383 | 2,557 | **0.150×** | 113,948 | 6,373 |
| `flagstaff/ora` | `ora` | 55,760 | 59,460 | **0.938×** | 717,066 | 285,079 |
| `flagstaff/boxen` | `boxen` | 28,671 | 41,105 | **0.698×** | 717,066 | 804,192 |
| `flagstaff/cli-table3` | `cli-table3` | 24,403 | 34,620 | **0.705×** | 717,066 | 153,737 |
| `flagstaff/spinner` | `ora` | 7,207 | 59,460 | **0.121×** | 717,066 | 285,079 |
| `flagstaff/box` | `boxen` | 20,696 | 41,105 | **0.503×** | 717,066 | 804,192 |
| `flagstaff/table` | `cli-table3` | 19,184 | 34,620 | **0.554×** | 717,066 | 153,737 |
| `flagstaff/log-update` | `log-update` | 18,751 | 36,300 | **0.517×** | 717,066 | 262,051 |
| `linegauge` | `string-width` | 5,646 | 6,013 | **0.939×** | 111,604 | 37,194 |
| `linegauge/wrap` | `wrap-ansi` | 11,427 | 14,372 | **0.795×** | 111,604 | 80,578 |
| `linegauge/slice` | `slice-ansi` | 11,411 | 14,634 | **0.780×** | 111,604 | 66,999 |
| `linegauge/strip` | `strip-ansi` | 272 | 457 | **0.595×** | 111,604 | 10,484 |
| `paratext` | `ansi-escapes` | 7,102 | 4,351 | **1.632×** | 119,615 | 30,912 |
| `bellpull` | `tinyexec` | 5,883 | 5,969 | **0.986×** | 116,702 | 26,969 |
| `seniority/lilconfig` | `lilconfig` | 3,286 | 5,343 | **0.615×** | 233,514 | 17,959 |
| `seniority/dotenv` | `dotenv` | 5,966 | 11,481 | **0.520×** | 233,514 | 45,996 |
| `closeout/exit-hook` | `exit-hook` | 4,819 | 1,645 | **2.929×** | 130,122 | 13,200 |
| `closeout/signal-exit` | `signal-exit` | 3,634 | 2,856 | **1.272×** | 130,122 | 76,966 |
| `controlroom/ink + react + react-reconciler` | `ink + react` | 531,706 | 673,137 | **0.790×** | 3,424,890 | 8,165,450 |
| `controlroom` | `ink` | 40,354 | 642,330 | **0.063×** | 1,312,767 | 7,986,787 |

## Reproduce

```bash
npm install
npx turbo run build
npm run bench -- --check
```

Results are written to `benchmarks/results/<suite>/<date>.json` and read by the Stage 6
control bands in `.sdlc/bands/control-bands.json`. The suite refuses to emit a band value
it did not measure; see `benchmarks/README.md`.

---

# Start from a boilerplate

> Copy a working controlroom app and change it, instead of starting from an empty file.

Source: https://burgee.interlace.tools/docs/boilerplates

Each boilerplate is a directory under
[`examples/`](https://github.com/ofri-peretz/burgee/tree/main/examples) that runs as it is, is
tested by this repository's CI in a pipe, under `--json` and on a terminal, and has a README
that says what to change first. Copy one; there is no generator to install.

| Boilerplate | What it is | Copy it |
| :-- | :-- | :-- |
| [`chat-cli`](https://github.com/ofri-peretz/burgee/tree/main/examples/chat-cli) | A chat CLI in the shape of Claude Code, inline: a streamed markdown reply, slash commands with completion, a permission prompt, a status line, Esc to interrupt | `npx degit ofri-peretz/burgee/examples/chat-cli my-chat` |
| [`chat-cli-ink`](https://github.com/ofri-peretz/burgee/tree/main/examples/chat-cli-ink) | The same chat written for Ink (`ink`, `react`, `ink-text-input`), run on `controlroom/ink` through one `package.json` line | `npx degit ofri-peretz/burgee/examples/chat-cli-ink my-chat` |
| [`dashboard`](https://github.com/ofri-peretz/burgee/tree/main/examples/dashboard) | A full-screen dashboard: tabs, a checklist with progress, a log tail and a status line that collapses | `npx degit ofri-peretz/burgee/examples/dashboard my-dashboard` |

`chat-cli-ink` runs unchanged on ink itself when that one line points back at ink: it is the
proof that a whole Ink app, not just its components, moves by changing a dependency.

## Every caller, from one program

Each boilerplate draws its screen only for a person at a terminal. A pipe, CI and a screen
reader get clean lines, and an agent gets NDJSON on stderr under `--json`. Nothing waits for a
key that nobody can press: piped input is read a line at a time, and a closed stdin ends the
program.

```bash
node chat.mjs                              # a terminal
printf 'hello\n' | node chat.mjs           # a pipe
printf 'hello\n' | node chat.mjs --json    # an agent
```

## Why there is no create-* package

A generator would be an eleventh package against the family's cap of ten (D-158), for what
`degit` already does. It is reopened if copying a directory is measured to be the friction.

---

# Changelog

> Every release of burgee, newest first, from its CHANGELOG.md — what changed and the pull request it came from.

Source: https://burgee.interlace.tools/docs/changelog

## 1.6.7

### Patch Changes

- [#1203](https://github.com/ofri-peretz/burgee/pull/1203) [`801875d`](https://github.com/ofri-peretz/burgee/commit/801875de1252846b59e5bfa024ca716818316847) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - The precedence order is now exported as a truth table. `TRUTH_TABLE` has 32 rows, one for each combination of the five sources (flag, env, config, package, default). Each row lists the sources that set a value and names the one that wins. It is `truthTable(ORDER)`, so it always matches the order `resolve` uses, and the new docs page [The truth table](https://seniority.interlace.tools/docs/guides/truth-table) is generated from it.

  Provenance through `extends` now names the right file. When a config extends another, a value set only by the parent used to be credited to the extending file, which does not contain it. The loaded layer now has `origins`: for each key, the nearest file in the chain that set it, and that file's line. `resolve`, `explain` and `--json` provenance cite that file and line. A file that extends nothing loads the same as before.

  burgee: `--explain` and `meta.provenance` now give the line for a value set in a config file (`app.config.json:3`). They also name the file in an `extends` chain that set it, not the whole chain joined into one location.

- Updated dependencies [[`801875d`](https://github.com/ofri-peretz/burgee/commit/801875de1252846b59e5bfa024ca716818316847)]:
  - seniority@1.1.0

## 1.6.6

### Patch Changes

- [#1186](https://github.com/ofri-peretz/burgee/pull/1186) [`af24328`](https://github.com/ofri-peretz/burgee/commit/af243288e27cbffbcffac18af7112172e46a003b) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Published declarations now keep each doc comment's first paragraph, its code examples and its `@param`, `@returns`, `@throws`, `@example`, `@deprecated`, `@default` and `@see` tags, and drop the longer design notes below them, so the tarballs are smaller (burgee by 5.7% gzipped, bellpull and closeout by about a fifth). Types are unchanged, and hover text in an editor keeps its summary. `burgee`'s README also names `burgee/program-schema.json`, the JSON Schema every `--schema` document validates against.
- Updated dependencies [[`af24328`](https://github.com/ofri-peretz/burgee/commit/af243288e27cbffbcffac18af7112172e46a003b), [`122635d`](https://github.com/ofri-peretz/burgee/commit/122635dce20998d1cba0eaa3c9df9c38bfd47c8b)]:
  - bellpull@1.0.9
  - closeout@1.1.6
  - linegauge@1.1.4
  - roundel@1.2.0
  - seniority@1.0.12

## 1.6.5

### Patch Changes

- [#1160](https://github.com/ofri-peretz/burgee/pull/1160) [`0b381a0`](https://github.com/ofri-peretz/burgee/commit/0b381a0d394092edf2ea21a9143a10111aa72fe4) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Export `./package.json`. `require('<package>/package.json')` threw `ERR_PACKAGE_PATH_NOT_EXPORTED`, which broke tools that read a dependency's manifest that way: bundlers, license scanners and version checks.
- Updated dependencies [[`0b381a0`](https://github.com/ofri-peretz/burgee/commit/0b381a0d394092edf2ea21a9143a10111aa72fe4)]:
  - bellpull@1.0.8
  - closeout@1.1.5
  - linegauge@1.1.3
  - roundel@1.1.3
  - seniority@1.0.11

## 1.6.4

### Patch Changes

- [#1152](https://github.com/ofri-peretz/burgee/pull/1152) [`a34a8ee`](https://github.com/ofri-peretz/burgee/commit/a34a8eefafac2be5dd0d15f08c58eb760c40741d) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - A program on `burgee/yargs` now shows its `.conflicts()`, `.implies()` and `.example()` in `--schema` and in the `--mcp` tool list. Until now all three were dropped. `.conflicts()` appears as `exclusive` and `.implies()` as `dependsOn`, both under the option's canonical name, even when the program declared the relation on an alias or named an alias in it. `.example()` appears as `examples`, with `$0` spelt as the program name. A relation that names no option is left out: a positional count (`.implies('key', 1)`), a `--no-x` negation, or a dotted key. The commander front-end already projected its `.conflicts()`. yargs' own help and parsing are unchanged (816 / 816 on its suite). `burgee/yargs` bundles 424 B larger, at 108,769 B, which is still lighter than yargs' 111,686 B.

## 1.6.3

### Patch Changes

- [#1139](https://github.com/ofri-peretz/burgee/pull/1139) [`28843a5`](https://github.com/ofri-peretz/burgee/commit/28843a536a3ec3bcd4b201a47436c4c672a16b65) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - A `fix:` line is quoted for the shell that will run it: POSIX `sh` off Windows, as before, and
  PowerShell on Windows, where a quote inside a word is doubled (`'it''s'`) and a word that starts
  with `@`, contains `,` or is `--%` is quoted too. A fix line printed on Windows used to be a
  PowerShell syntax error for any word with a `'` in it.

  Root help's `Exit codes:` section, `--schema`'s `errors` and the skill's contract table now list
  only the codes the program can produce. `auth` is listed when the program declares the credential
  it reads, `defineProgram({ auth: { env: 'DEMO_TOKEN' } })`, and its advice then names the variable:
  `set DEMO_TOKEN and run it again`. That sentence is also an `AuthError`'s hint when the handler
  gives none. `timeout` is left out when every command declares its own `timeout` option.

- [#1138](https://github.com/ofri-peretz/burgee/pull/1138) [`6b90ffe`](https://github.com/ofri-peretz/burgee/commit/6b90ffed8cd883b26f94fc3b690c1e2beb41ec83) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee migrate` reads dotenv 18.0.8 and lilconfig 3.1.4 as the graded releases of `seniority/dotenv` (193 / 193, control 193 / 193) and `seniority/lilconfig` (77 / 77, control 77 / 77).
- Updated dependencies [[`6b90ffe`](https://github.com/ofri-peretz/burgee/commit/6b90ffed8cd883b26f94fc3b690c1e2beb41ec83)]:
  - seniority@1.0.10

## 1.6.2

### Patch Changes

- [#1130](https://github.com/ofri-peretz/burgee/pull/1130) [`c05c86e`](https://github.com/ofri-peretz/burgee/commit/c05c86e2caa0fc3a89f97f7fe9c37bd7b876bfaf) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Every drop-in subpath now type-checks under `moduleResolution: node10`, and under `module: commonjs`
  with no resolution set, which is TypeScript's default there. `import … from 'burgee/commander'`
  used to fail with TS2307 in such a project, although `require()` of the same specifier worked.
  Each package now declares `types` and a `typesVersions` map, derived from `exports`, with one key per
  typed subpath pointing at the file `exports` already names. `exports` is unchanged, so `node16`,
  `nodenext` and `bundler` read exactly what they read before. `controlroom/ink`'s declarations no
  longer name the untyped `react-reconciler`, which was TS7016 for consumers with `skipLibCheck: false`.
- Updated dependencies [[`c05c86e`](https://github.com/ofri-peretz/burgee/commit/c05c86e2caa0fc3a89f97f7fe9c37bd7b876bfaf)]:
  - bellpull@1.0.7
  - closeout@1.1.4
  - linegauge@1.1.2
  - roundel@1.1.2
  - seniority@1.0.9

## 1.6.1

### Patch Changes

- [#1124](https://github.com/ofri-peretz/burgee/pull/1124) [`db0ad9b`](https://github.com/ofri-peretz/burgee/commit/db0ad9b688790ec9979a52c2f76f45862800ef35) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee migrate`: under a minimum release age, `next` never pins a family package below the first release that exports every subpath the rewrite imports. On svgo it printed `pnpm add roundel@^1.0.4` for three imports of `roundel/picocolors`, which first shipped in roundel 1.1.0, and the migrated CLI could not start. It now pins `roundel@^1.1.0`, and when no such release is old enough yet the note names the subpath and the date the first one that carries it can install. Each pin it moves for this reason carries `requires: { specifiers, since }`. The table of first versions is read from this repository's release tags at build time and ships in `dist/family-versions.json`; nothing new is fetched at run time.

## 1.6.0

### Minor Changes

- [#1091](https://github.com/ofri-peretz/burgee/pull/1091) [`dc1d1d1`](https://github.com/ofri-peretz/burgee/commit/dc1d1d196bafa63df5580135a8c42b324480fc9e) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee/commander` publishes an `Argument`'s `.choices()` as `enum` on the positional, in
  `--schema` and in `--mcp`'s `inputSchema`, the way an option's choices already are (a variadic
  argument's go on its items). `ArgumentSpec` gains `choices`; native `defineCommand` does not
  accept it yet, because its parser does not check a positional's value. Commander's own help and
  parsing are unchanged.

- [#1091](https://github.com/ofri-peretz/burgee/pull/1091) [`dc1d1d1`](https://github.com/ofri-peretz/burgee/commit/dc1d1d196bafa63df5580135a8c42b324480fc9e) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee/commander` projects what a program already declares: `Option.choices()` becomes `enum` in
  `--schema` and in `--mcp`'s `inputSchema` (and the values completions offer), `.hideHelp()` keeps
  an option out of the input schema, help and completions, `.conflicts()` is published as `exclusive`
  and in the command's `relations`, and an `Argument`'s string default reaches the positional's
  `default`. Commander's own help and parsing are unchanged.

### Patch Changes

- [#1037](https://github.com/ofri-peretz/burgee/pull/1037) [`50cc502`](https://github.com/ofri-peretz/burgee/commit/50cc5024df7a99ecd2dff33570eea21730b87b99) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `@inquirer/prompts`' graded drop-in is `caique/inquirer/prompts`, now 100 / 213. `burgee migrate` still reports it rather than rewriting it, because it is not level yet.

## 1.5.0

### Minor Changes

- [#1039](https://github.com/ofri-peretz/burgee/pull/1039) [`3bd9a9e`](https://github.com/ofri-peretz/burgee/commit/3bd9a9eaba812776c87dbea1def87e850599219d) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee/commander/extra-typings` is a new entry point: a drop-in for `@commander-js/extra-typings`, graded 369 of 369 by its own tsd suite, level with the control. Its JavaScript re-exports `burgee/commander`, as extra-typings re-exports commander; its declarations are extra-typings 15.0.0's, ported with their MIT notice, so options and arguments are inferred from the strings that declare them and `.opts()` and an action's parameters are typed without a cast. `burgee migrate` now rewrites `@commander-js/extra-typings`.

  It bundles to 61,207 B, what `burgee/commander` bundles to, against 39,329 B for `@commander-js/extra-typings` plus `commander`: a re-exporting door takes `burgee/commander`'s position (D-20261012-extra-typings-inherits-front-end), and the overage is `commander-front-end-diet`'s to close.

- [#1083](https://github.com/ofri-peretz/burgee/pull/1083) [`c736740`](https://github.com/ofri-peretz/burgee/commit/c7367408fbed1b66e13172e71a39bf050afa2cdd) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Command aliases, on every surface. A native command declares `aliases: ['s']`, and `prog s` runs it,
  at any depth (`prog r a` is `prog remote add`). `--schema` lists the aliases on the command and never
  as a command of their own, help prints them the way commander does (`serve|s`), the bash, zsh, fish
  and PowerShell scripts and the Fig spec offer and follow them, `__complete`, `help <command>` and
  `--schema <command>` read them, and `--mcp` names one tool per command by its canonical path.
  `burgee/commander`'s `.alias()` / `.aliases()` and `burgee/yargs`' `['serve', 's']` or `aliases:` now
  reach `--schema` the same way; both façades' own help and parsing are unchanged.

- [#1073](https://github.com/ofri-peretz/burgee/pull/1073) [`2fcd04e`](https://github.com/ofri-peretz/burgee/commit/2fcd04e7f5703f57b9698c2accc7e7c8ba80f097) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `--mcp` negotiates the protocol revision. `initialize` answers the client's `protocolVersion` when it is one the server supports, `2025-06-18` or `2025-11-25`, and the latest it supports, `2025-11-25`, otherwise, as the specification's negotiation rule asks. A client on `2025-06-18` gets exactly what it got before. `MCP_PROTOCOL_VERSION` (from `burgee/mcp`) is now `2025-11-25`, the latest revision served. `2026-07-28`, which has no `initialize`, is not served: a client asking for it in an `initialize` gets `2025-11-25`, and a dual-era client that probes `server/discover` first gets `method not found` and falls back to `initialize`.

- [#1064](https://github.com/ofri-peretz/burgee/pull/1064) [`e8e02fa`](https://github.com/ofri-peretz/burgee/commit/e8e02faec8df56dcd730407e570cb48a22454303) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - A native command (`defineCommand`, `defineProgram`) refuses input it used to drop. Both are usage errors, exit 2, before anything runs:

  - **More positionals than the command declares.** `demo greet ada extra` against a command that takes one argument now says `too many arguments: expected 1, got 2 ("extra")`. Before, `extra` was silently dropped and the run exited 0. A variadic last argument still takes the rest, and words after `--` are still `passthrough`.
  - **A single-value option given twice with different values.** `--level info --level debug` now says `--level was given twice: "info" and "debug"`. Before, `info` was silently dropped. The same value twice is still accepted, as are `multiple` options and booleans, and a value from the environment or config never conflicts with a flag.

  Each refusal carries a `fix`: the line as typed with the surplus words removed, or with only the last value of the repeated flag kept, ready to run. Both messages are in the locale catalog, so a locale pack translates them; `--json` stays English.

  A command that forwards its tail to a child process declares `allowExcess: true` to keep today's behaviour: the surplus reaches `ctx.positionals`, and `--schema` publishes `excess: true` for it. The commander and yargs drop-ins are unchanged.

### Patch Changes

- [#1078](https://github.com/ofri-peretz/burgee/pull/1078) [`91a67e9`](https://github.com/ofri-peretz/burgee/commit/91a67e9f50bbad08d2335a66df0635fd31f6359f) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee/commander` is 4.9 KB lighter in a bundle: 61,272 → 56,418 B on `/docs/weight`. An executable subcommand spawns through commander's own `child_process.spawn` on every path commander 15 takes. `bellpull/cross-spawn` now loads only for the one path commander can't run, a Windows executable that isn't launched through node (a `.cmd`, a `.bat`, a non-node shebang), and that spawn happens once the import settles. Nothing else changes: commander's suite still grades 1360 / 1360.

- [#1079](https://github.com/ofri-peretz/burgee/pull/1079) [`264a413`](https://github.com/ofri-peretz/burgee/commit/264a413388d846178cea4176743cd65aa2b5d65a) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee/commander` loads the code that serves `completion <shell>` and `--mcp` only when one of them is asked for, which takes 757 B off its start-up bundle (56,418 → 55,661 B on `/docs/weight`). Both surfaces behave as before. `--schema` still answers inside a synchronous `parse()`.

- [#1082](https://github.com/ofri-peretz/burgee/pull/1082) [`4a62884`](https://github.com/ofri-peretz/burgee/commit/4a6288481a77dce34c496af5a5ffbaed900483c6) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee check` refuses a locale pack with every problem at once: `refused.problems` lists each one with its own `fix`, and `refused.message` and `refused.fix` list them all, numbered. Before, it stopped at the first, so a pack with three mistakes took three runs. A missing plural form's fix now gives each form the locale selects with a count for it, e.g. `one (for 0), many (for 1000000), other (for 2) for fr`. `burgee/locale-pack-schema.json` names the plural forms of the common languages in the plural message's description and gives a French example, since French needs `many` and the German example does not show it.
- Updated dependencies [[`48ccbaf`](https://github.com/ofri-peretz/burgee/commit/48ccbaf47b5363978e080acbfd5f63add7655d46)]:
  - seniority@1.0.8

## 1.4.0

### Minor Changes

- [#1044](https://github.com/ofri-peretz/burgee/pull/1044) [`4c85515`](https://github.com/ofri-peretz/burgee/commit/4c8551599933c995e42060a60a1dc791eb1cd719) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Help, usage errors and hints can speak the user's language. A locale pack is a plugin that carries `locales`: a language tag mapped to catalog ids and their translations. You register it with `program.use(pack)`. It is written against the new `burgee/locale-pack-schema.json`, which lists every message id with its English. The locale comes from the new `locale` run option, then `BURGEE_LOCALE`, then `LC_ALL`, `LC_MESSAGES` and `LANG` (`C` and `POSIX` mean the program's own words). When an agent is detected, `LANG` is ignored. A message with `{count}` takes the plural forms `Intl.PluralRules` selects for the locale. `burgee check <pack>` renders every message, or refuses an unknown id, a placeholder the English lacks, or a missing plural form, with `E_PLUGIN_SCHEMA` and a fix. A pack that cannot be rendered fails the help it would translate as a CONFIG error.

  `description`, `summary`, an example's description and an option's description accept `{ en: '…', fr: '…' }`, base language first. Help and `--skill` show the run's locale, and `--schema`, `--mcp`, completions and the files `burgee skill` writes keep the base language.

  `--json`, `--schema`, `--mcp`, `--format=agent`, error kinds and exit codes never change with the locale, and the `error:`, `hint:` and `fix:` labels stay English. With no pack registered and no localised text, every byte of output is unchanged. The commander, yargs and meow front-ends are unchanged.

- [#1061](https://github.com/ofri-peretz/burgee/pull/1061) [`eca6e58`](https://github.com/ofri-peretz/burgee/commit/eca6e585095486c1b584dc69c4dd0753b501fd91) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `--mcp` serves calls concurrently, honours `notifications/cancelled`, and sends progress. A request no longer waits for the one before it, so a client can cancel a call while it runs: the call's `ctx.signal` aborts with the reason `cancelled`, its `ctx.onExit` handlers run once as they do after a timeout, and no response is sent for it, as the protocol requires. A cancellation for an unknown or finished request is ignored. Replies go out in the order calls settle.

  `ctx.progress(done, total?, message?)` is new on every handler's context. Inside an `--mcp` call whose client sent `_meta.progressToken`, each call sends `notifications/progress` with that token, once the value rises above the last one sent. Everywhere else it does nothing, so a handler calls it unconditionally.

- [#1048](https://github.com/ofri-peretz/burgee/pull/1048) [`10edb48`](https://github.com/ofri-peretz/burgee/commit/10edb489060fa73a54a094be5129e8cdc52e4a09) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `--mcp --print-config` prints the `mcpServers` block that starts this program as an MCP server, ready to paste into a client's configuration. A program started as one of its package's bins, through the symlink npm installs or by its own path, is started by that bin's name, through `cmd /c` on Windows, where npm installs it as a `.cmd` shim a client cannot start directly; anything else is started as `node` with the script's full path. The server is keyed by the program's name. It is read on burgee's own API; the commander and yargs front ends do not read it yet.

### Patch Changes

- [#1060](https://github.com/ofri-peretz/burgee/pull/1060) [`52f6c71`](https://github.com/ofri-peretz/burgee/commit/52f6c71d2db4bc3fd9cbfd9e83fedb5f3ea359dc) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `--quiet` reaches `caique/clack`'s decoration. Every clack call's options take an optional `runtime` (roundel's policy `Runtime`, which is burgee's `ctx.runtime`). When it says `quiet`, `spinner`, `tasks`, `intro`, `outro`, `note` and `log.message`, `info`, `step`, `success` and `warn` write nothing, and the spinner arms no interval; their lifecycle methods still run. `log.error` and `cancel` still write, and prompts ignore `quiet`. A call without a `runtime` behaves exactly as before, and quiet is never read from argv or the environment. `isCI()` takes an optional runtime to read `CI` from.

  burgee's README shows the call under For agents: `spinner({ runtime: ctx.runtime })`.

- [#1046](https://github.com/ofri-peretz/burgee/pull/1046) [`1797388`](https://github.com/ofri-peretz/burgee/commit/1797388f27a294803b12839ff4d074226bd40917) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee dev` serialises reloads that pile up during one. Two saves landing while a reload was in flight both waited on the same link, then imported at once — and when the older import finished last, the server kept serving its stale commands. Each save now queues behind the one before it, so the newest save is the one served.
- Updated dependencies [[`1797388`](https://github.com/ofri-peretz/burgee/commit/1797388f27a294803b12839ff4d074226bd40917)]:
  - closeout@1.1.3

## 1.3.0

### Minor Changes

- [#1043](https://github.com/ofri-peretz/burgee/pull/1043) [`c884177`](https://github.com/ofri-peretz/burgee/commit/c884177824aa6187e7167cdb8029ec8f15572c4c) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Every program prints an Agent Skill. `--skill` writes a `SKILL.md` to stdout, projected from the declaration: front matter with a `name` and `description` within the Agent Skills specification's limits, what the program is for, the contract an agent relies on (`--json` and its envelope, `--explain`, every exit code with its error kind and whether to retry), and one line and the first example per command. A command's options stay behind `--schema <command>`, which the skill names and never inlines. A root that declares its own `skill` option keeps it.

  `burgee skill <entry>` writes `SKILL.md` and `AGENTS.md` (the same body under an `AGENTS.md` heading, no front matter) into the directory of the `bin` the entry's package.json names, or `--out <dir>`. `--check` writes nothing and exits 1 when the files there differ from the projection, naming them and the line that regenerates them, for an author's CI.

  Root help's line for agents names `AGENTS.md` when one sits beside the binary or in the directory above it. Without the file the line is unchanged.

- [#1051](https://github.com/ofri-peretz/burgee/pull/1051) [`7500480`](https://github.com/ofri-peretz/burgee/commit/75004801fd3f6e91069861bd20820bc11523c149) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `--mcp` lists `outputSchema` for a command that declares `output.schema`. The schema is listed as declared when it is an object type, and wrapped as `{ "type": "object", "properties": { "result": … }, "required": ["result"] }` otherwise, the same way `structuredContent` wraps a result that is not an object. A declared command's `structuredContent` is wrapped by its schema rather than by the value, so it always has the shape the tool advertised. A command without `output.schema` lists no `outputSchema`. JSON a handler printed without a boolean `ok` is not read as an envelope, so it carries no `structuredContent`. The `Tool` type gains the optional `outputSchema`.

### Patch Changes

- [#1045](https://github.com/ofri-peretz/burgee/pull/1045) [`c4fd9a3`](https://github.com/ofri-peretz/burgee/commit/c4fd9a3cb10bc36bef8c468365addfc6deb572cf) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - caique's own chrome can speak the user's language. That covers the instruction under a list, a problem with an answer, the giving-up line, and the no-terminal and cancel refusals. A locale pack registered with `register()` carries translations under ids that begin `caique.`, so one object can serve burgee's catalog too. The new `caique/locale` entry turns the runtime's `locale` into the translator: `io.say = sayFor(runtime.locale)`. `ask` and `resolvePrompts` apply it. Neither reads the catalog itself, and caique never reads `LANG`. A refusal keeps its English `message` and `fix`, which a host may put in a machine envelope, and adds `localised` beside them. `caique check` renders a pack's messages, or refuses an unknown id, a stray placeholder or a missing plural form with `E_PLUGIN_SCHEMA`. With no `say` handed in, every byte is unchanged, and `caique/clack` and `caique/inquirer` keep their incumbents' English.

  burgee: the family plugin schema it publishes describes the `locales` key.

- Updated dependencies [[`c4fd9a3`](https://github.com/ofri-peretz/burgee/commit/c4fd9a3cb10bc36bef8c468365addfc6deb572cf)]:
  - bellpull@1.0.6
  - closeout@1.1.2
  - linegauge@1.1.1
  - roundel@1.1.1
  - seniority@1.0.7

## 1.2.0

### Minor Changes

- [#1015](https://github.com/ofri-peretz/burgee/pull/1015) [`e0532b2`](https://github.com/ofri-peretz/burgee/commit/e0532b2cf298c183699621fc6e17e59373f83bad) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Every failure names its kind. The `--json` envelope's `error` carries `kind` beside the numeric `code` (`runtime`, `usage`, `config`, `cancelled`, `auth`, `timeout`, `interrupted`, or your own), and `--schema` lists every kind under a new `errors` key with its `exit_code`, whether it is `retryable`, and a `description`, in clispec v0.3's shape. `schemaVersion` stays 1: the key is new and nothing changes meaning.

  `defineError` takes an optional `kind`, `retryable` and `description`. Without `kind`, a class's kind is its name in snake case less a trailing `Error` (`QuotaError` is `quota`); a declared one must be snake_case and one class's alone. A name whose kind is already held, such as `TimeoutError` beside the contract's `timeout`, is told apart by its code (`timeout_12`), so every class that defined before still defines.

  stderr ends with the failure as one JSON line, `{"error":{"kind","code","message"}}`, whenever it is not a terminal: always under `--json` (stdout's envelope is unchanged), and after the prose when stderr is piped or captured. At a terminal stderr is unchanged. The commander and yargs front-ends are unchanged.

- [#1027](https://github.com/ofri-peretz/burgee/pull/1027) [`a2e4f98`](https://github.com/ofri-peretz/burgee/commit/a2e4f98c5524f59c24c560130a8c9cfbcb961991) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `--schema` is a clispec v0.3 document (https://clispec.dev). Beside burgee's own keys, which keep their meaning (`schemaVersion` stays 1), a native program's document now carries `clispec: "0.3"`, a `version` always (the declared one, else the owning `package.json`'s), `global_args` (the rows root help lists under `Global options:`), and `output` (`{ tty: "text", piped: "text", formats }`). Each command carries `example` (its first example as `{ args }`), and from a new `output` declaration `cardinality`, `output_kind`, `media_type` and `stdout_schema`. The commander and yargs front-ends are unchanged.

  `defineCommand` takes `output: { kind?, cardinality?, schema?, mediaType? }`. With a `schema`, TypeScript holds `run`'s return to what it describes; without one, nothing changes. `burgee dev` warns about a runnable command that declares no `output.cardinality`, and refuses nothing.

  `--format text` (also `--format=text`, `--output text`) prints the human rendering, under a pipe or an agent alike: it was `unknown option --format`, exit 2. A command that declares its own `--format` keeps it.

- [#1034](https://github.com/ofri-peretz/burgee/pull/1034) [`d8569f5`](https://github.com/ofri-peretz/burgee/commit/d8569f53c31382a864d5a86b5a3b720b7918476f) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Help renders as Markdown. `renderHelp(manifest, node, { format: 'markdown' })` from `burgee/help` returns a promise of the same help as Markdown: a heading for the command, its usage in a code block, each section (arguments, options, global options, commands, exit codes, environment) as a table, and each example as a fenced line. It is a second layout of the same section list `--help` draws, so the two cannot list different things. The Markdown layout loads only when asked for; terminal help is unchanged, byte for byte.

- [#1047](https://github.com/ofri-peretz/burgee/pull/1047) [`206d2a8`](https://github.com/ofri-peretz/burgee/commit/206d2a8da4bbac20f5b6370989f103b3de86c2bf) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `--mcp` tool results carry `structuredContent`. When a call's stdout is the `--json` envelope, the result carries the envelope's `data` as `structuredContent` (wrapped as `{ "result": data }` when it is not an object, since the protocol requires one), or the envelope's `error` with `isError: true` on a failure. The text content stays first and unchanged, so a client that reads only text sees what it saw before. A run that printed prose rather than an envelope carries no `structuredContent`.

### Patch Changes

- [#1008](https://github.com/ofri-peretz/burgee/pull/1008) [`bcc438a`](https://github.com/ofri-peretz/burgee/commit/bcc438ac3936ee1cd530931ea090c6a8bdd016b2) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee migrate` now rewrites `picocolors` to `roundel/picocolors`, which picocolors 1.1.1's own test passes, level with picocolors itself.

- [#1012](https://github.com/ofri-peretz/burgee/pull/1012) [`49d8e94`](https://github.com/ofri-peretz/burgee/commit/49d8e943ceaf8dcef14d43c0a70c2edec1a67816) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `@inquirer/prompts` is now graded: its ten prompts' own suites (8.7.3) are vendored and run against `caique/inquirer`, with a control of 213 of 213 against the real packages. `caique/inquirer` passes 0 of them today, because it exports `@inquirer/core`'s surface and none of the prompts yet, and `burgee migrate` reports `@inquirer/prompts` as a graded path that is not level, never rewriting it. The eleven `@inquirer/editor` cases are excluded by title: each answers the prompt through a mock of `@inquirer/external-editor`, which caique does not import.

  The oracle gains two host fields for it. `suiteFiles` lists a monorepo suite's files across several packages and vendors only those; `defaultExport` grades a suite that imports its prompt as a default against the named export a program migrates.

- [#1007](https://github.com/ofri-peretz/burgee/pull/1007) [`bfe4ab8`](https://github.com/ofri-peretz/burgee/commit/bfe4ab8b13ff04293345a69007cad9e0cb81c678) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Two new drop-in subpaths, each graded by its incumbent's own suite and level with it. `linegauge/cli-truncate` is cli-truncate 6 (12 of 12): its default export and `position`, `space`, `preferTruncationOnSpace` and `truncationCharacter`, over linegauge's own `slice` and `width`. `linegauge/widest-line` is widest-line 6 (1 of 1) over `widest`. `truncate` and `widest` are unchanged. `burgee migrate` now rewrites `cli-truncate` and `widest-line`.

- [#1029](https://github.com/ofri-peretz/burgee/pull/1029) [`35ded07`](https://github.com/ofri-peretz/burgee/commit/35ded075ffcc7175bc5dffb5b8d0210a584571f9) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee migrate`'s release-age version order no longer carries a comparison of major versions it can never make: every candidate is already of the graded major.

- [#1022](https://github.com/ofri-peretz/burgee/pull/1022) [`ecb0a00`](https://github.com/ofri-peretz/burgee/commit/ecb0a00ca68e9a3b3584aefabb9dcf97e3ff967a) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - The tarball no longer carries declaration files that no `exports` entry reaches. TypeScript could never open them, because a deep import is refused by `exports`. Every entry's types are unchanged. The ten packages drop 71 files and 118,312 bytes between them, burgee 35 files and 76,504 bytes, which takes its tarball from 251,814 to 225,278 bytes gzipped.
- Updated dependencies [[`bfe4ab8`](https://github.com/ofri-peretz/burgee/commit/bfe4ab8b13ff04293345a69007cad9e0cb81c678), [`1968eb4`](https://github.com/ofri-peretz/burgee/commit/1968eb46feec57bb047a9c4a4288e0cf4442f4b2), [`65afee5`](https://github.com/ofri-peretz/burgee/commit/65afee5c96e4cae62dbb9b0ba28fab98fffdbf01), [`bcc438a`](https://github.com/ofri-peretz/burgee/commit/bcc438ac3936ee1cd530931ea090c6a8bdd016b2), [`ecb0a00`](https://github.com/ofri-peretz/burgee/commit/ecb0a00ca68e9a3b3584aefabb9dcf97e3ff967a)]:
  - linegauge@1.1.0
  - roundel@1.1.0
  - bellpull@1.0.5
  - closeout@1.1.1
  - seniority@1.0.6

## 1.1.0

### Minor Changes

- [#1006](https://github.com/ofri-peretz/burgee/pull/1006) [`733e5e0`](https://github.com/ofri-peretz/burgee/commit/733e5e0f1bbca8231275202df47fad2a9fe18944) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Every command takes three global options. `--no-color` and `--color=always|never|auto` reach help and the handler's new `ctx.runtime`, which carries the caller's colour flag and `quiet` to roundel's policy and flagstaff's `hoist`. `-q`/`--quiet` silences progress and framework hints, such as a deprecation warning, and never data or errors. `--timeout <duration>` (`500ms`, `5s`, `2m`) aborts the new `ctx.signal`, runs the exit handlers once and leaves with the new `ExitCode.TIMEOUT`, 6. All three can be typed before the command too. A command that declares an option of the same name keeps it. Root and command help list them under `Global options:`.

- [#1002](https://github.com/ofri-peretz/burgee/pull/1002) [`a049bc2`](https://github.com/ofri-peretz/burgee/commit/a049bc2bee2a461b141d2eb2819cefbc01df7949) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Root help now carries what a caller branches on and what to type. It lists the `completion <shell>` command the engine serves, an `Exit codes:` section generated from `ExitCode`, and an `Examples:` section: the root's own (`defineProgram({ examples })`, new) or each top-level command's first example. `--schema` publishes `completion` beside the program's commands, and `completion --help` prints its help. `burgee dev` warns about a runnable command that declares no examples.

### Patch Changes

- [#1005](https://github.com/ofri-peretz/burgee/pull/1005) [`079250e`](https://github.com/ofri-peretz/burgee/commit/079250ebc3e0cc511df1269060854711f686b5b4) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Two new drop-in subpaths, each graded by its incumbent's own suite and level with it. `closeout/onetime` is onetime 8 (6 of 6): the default export, `callCount` and `{ throw: true }`, and like onetime it retries a first call that throws. `closeout/cli-cursor` is cli-cursor 5 (8 of 8): `{ show, hide, toggle }` on `process.stderr` by default, and a hide arranges the show at exit through `closeout/restore-cursor`. `burgee migrate` now rewrites `onetime` and `cli-cursor`.

  `closeout/restore-cursor` bundles 318 B less (4,648 to 4,330 B on /docs/weight): the process-wide `onExit` reaches the registry without the `Closeout` view, which carried the cursor pairing.

- [#991](https://github.com/ofri-peretz/burgee/pull/991) [`bd1a544`](https://github.com/ofri-peretz/burgee/commit/bd1a5444bcc035aa6f2db24b435dee4d4d8fc5d7) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee migrate`: under a pnpm `minimumReleaseAge`, `next` pins each family package to the newest release of its graded major that is old enough to install (from the registry's `time` field), respects `minimumReleaseAgeExclude`, and says when the install will start working if no version is old enough yet. `releaseAge` gains `exclude` and `pins`.

- [#1005](https://github.com/ofri-peretz/burgee/pull/1005) [`079250e`](https://github.com/ofri-peretz/burgee/commit/079250ebc3e0cc511df1269060854711f686b5b4) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `seniority/find-up` is now find-up 8's surface, graded by find-up 8.0.0's own suite: 104 of 104, level with find-up itself. It adds a matcher function with `findUpStop`, `findDown` and `findDownSync`, and locate-path's `type` and `allowSymlinks`; `cwd` and `stopAt` take a `URL`. Three behaviours follow find-up rather than seniority's resolver walk: `cwd` is optional and defaults to the process's working directory, a name matches a file unless `type` says otherwise, and `findUpMultiple` returns the first matching name per directory. `burgee migrate` now rewrites `find-up` to `seniority/find-up`.
- Updated dependencies [[`079250e`](https://github.com/ofri-peretz/burgee/commit/079250ebc3e0cc511df1269060854711f686b5b4), [`079250e`](https://github.com/ofri-peretz/burgee/commit/079250ebc3e0cc511df1269060854711f686b5b4), [`6f74a64`](https://github.com/ofri-peretz/burgee/commit/6f74a647c107307f11e1aef7092cf4e1afc6146d)]:
  - closeout@1.1.0
  - seniority@1.0.5

## 1.0.1

### Patch Changes

- [#938](https://github.com/ofri-peretz/burgee/pull/938) [`9babb6d`](https://github.com/ofri-peretz/burgee/commit/9babb6da1ae7783c7e8367f89e3da9dffc85ffdb) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - npm description and README: the description says what the package does, then its dependency fact in one of two wordings ("Zero dependencies." or "No dependency outside the burgee family."), then its drop-in paths. The README's family section states how the family is built — the leaves, one-way dependencies, nothing from outside the family, trusted publishing with provenance — and its table column is "Migrates from". No API, compatibility grade or benchmark changes.
- Updated dependencies [[`9babb6d`](https://github.com/ofri-peretz/burgee/commit/9babb6da1ae7783c7e8367f89e3da9dffc85ffdb)]:
  - bellpull@1.0.4
  - closeout@1.0.4
  - linegauge@1.0.8
  - roundel@1.0.4
  - seniority@1.0.3

## 1.0.0

### Major Changes

- [#919](https://github.com/ofri-peretz/burgee/pull/919) [`1ea5801`](https://github.com/ofri-peretz/burgee/commit/1ea5801521c36d235b5eb1156c78f7eaeefcd620) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - burgee 1.0.0. The spec is fully built (U9 and U12 closed 2026-10-09), every drop-in passes its incumbent's own suite at the latest release level with the incumbent itself (commander 15.0.0 1360 / 1360, yargs 18.2.0 816 / 816 against its own 814, meow 14.1.0 146 / 148 against its own 146), and coverage is 100% on all four measures (D-20261009-burgee-1-0-evidence). The published entries, the drop-ins, both schema files, the `burgee` bin and the agent contracts (the `--json` envelope, the versioned `--schema`, exit-code meanings and `fix:` lines) become a semver contract. No API changed in this release.

### Patch Changes

- [#921](https://github.com/ofri-peretz/burgee/pull/921) [`8d6f2e4`](https://github.com/ofri-peretz/burgee/commit/8d6f2e4171055bc4561043c8cda22424ffcae9ed) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `--schema` and the unknown-command hint now name `--explain`, for where a value came from.

  A native program's `--schema` document carries one new field just before `commands`:
  `"explain":"--explain <option> on a command says where its value came from: default, env, config or flag"`.
  An unknown command that matches nothing now hints `run --schema for every command and option as
JSON, in one call; --explain <option> says where a value came from`. In B1's transcripts, 56 of
  60 agents asked where a value came from read `--schema` and then spent three to eight turns
  probing the env var it named. `burgee/program-schema.json` describes the new field. One
  command's schema is unchanged. So is `--schema` on `burgee/commander` and `burgee/yargs`, which do
  not parse `--explain` (D-20261009-b1-totals-and-explain).

- [#917](https://github.com/ofri-peretz/burgee/pull/917) [`735f0f6`](https://github.com/ofri-peretz/burgee/commit/735f0f68048f2d0f5e4effad151ed5132b480bb8) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - README: the opening paragraph says what the package does first. The drop-in path follows it as one line, naming the incumbent and `npx burgee migrate`, and every compatibility row and benchmark is unchanged.

- [#917](https://github.com/ofri-peretz/burgee/pull/917) [`735f0f6`](https://github.com/ofri-peretz/burgee/commit/735f0f68048f2d0f5e4effad151ed5132b480bb8) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - README: the FAQ links the comparison guides by their new titles, "Switching from commander" and "Switching from yargs". The URLs are unchanged.
- Updated dependencies [[`735f0f6`](https://github.com/ofri-peretz/burgee/commit/735f0f68048f2d0f5e4effad151ed5132b480bb8)]:
  - bellpull@1.0.3
  - closeout@1.0.3
  - linegauge@1.0.7
  - roundel@1.0.3
  - seniority@1.0.2

## 0.23.0

### Minor Changes

- [#905](https://github.com/ofri-peretz/burgee/pull/905) [`4c05c47`](https://github.com/ofri-peretz/burgee/commit/4c05c47a4b62a238a5d9ea3d74957d5c005f43d7) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - A native burgee program now reads a request for JSON wherever and however it is typed, and every fix it prints runs.

  - **`--format json` is `--json`.** `--format json`, `--format=json`, `--output json` and `--output=json` now run the command with `--json`. They used to be refused with `fix: … --json`. A command that declares an option of that name keeps it, and a command that declares one near it (`--formats`) still gets the refusal, because then which was meant is a guess.
  - **`--json` before the command is read.** `demo --json config get user.name` and `demo --format json config get user.name` now run `config get user.name --json`. They used to be refused with `--json goes after the command`.
  - **A fix after a request for JSON starts where the request left off.** `demo --format json config user.name` printed `fix: demo config user.name --json`, which is refused in turn. It now prints `fix: demo config get user.name --json`.
  - **A dashed word where a command goes is matched by its name.** `demo --get user.name` printed `did you mean --eet?` and a fix naming a command that does not exist. It now prints `did you mean config get?` and `fix: demo config get user.name`.

  Only the request for JSON is ever read this way. A misspelt or misplaced command word is still a usage error with a `fix`, and nothing is run for you. The façades are unchanged: commander 1360/1360, yargs 816/816. The core entry is 58 bytes heavier and inside its ceiling.

## 0.22.4

### Patch Changes

- [#898](https://github.com/ofri-peretz/burgee/pull/898) [`8d601e7`](https://github.com/ofri-peretz/burgee/commit/8d601e7d7b7f82dc376fc224d05762c5ba291e3d) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - A run starts faster: the engine reads `parseArgs` and the `fs` calls behind `--version` and config discovery through `process.getBuiltinModule` instead of an ES `import` of `node:util` and `node:fs`. An ES import builds a namespace over every export and loads 24 Node internals to do it (`worker_threads`, `fs/promises`, `readline`), none of which a run calls. Measured over 300 interleaved spawns, the paired CPU ratio against cac fell from 1.590 to 1.517. No behaviour changes: the calls and the objects they are made on are the same.

## 0.22.3

### Patch Changes

- [#897](https://github.com/ofri-peretz/burgee/pull/897) [`f29f159`](https://github.com/ofri-peretz/burgee/commit/f29f159ca0c9746f58d8ba84eec9be72b1140093) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - controlroom has its own docs site at https://controlroom.interlace.tools: its README's Docs line, its `homepage`, and every family table now link there.
- Updated dependencies [[`f29f159`](https://github.com/ofri-peretz/burgee/commit/f29f159ca0c9746f58d8ba84eec9be72b1140093)]:
  - bellpull@1.0.2
  - closeout@1.0.2
  - linegauge@1.0.6
  - roundel@1.0.2
  - seniority@1.0.1

## 0.22.2

### Patch Changes

- [#891](https://github.com/ofri-peretz/burgee/pull/891) [`6b8e3d9`](https://github.com/ofri-peretz/burgee/commit/6b8e3d92d3c9fa217905bfa51bcb48da8d62fbf7) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Help and refusals in a native burgee program now put the whole line to run on the first screen.

  - **`--help` lists the commands that run by their full path.** When every command that runs fits in eight rows, the root help lists `config get <key>  Print one configuration value` where it listed `config  Read configuration`. It uses the same rule as the unknown-command listing. Hidden commands stay hidden, and a larger program keeps its group rows. `renderHelp` takes the list as a new optional `commands` option, and without it renders as before.
  - **A refused word that is really an argument gets a fix.** `demo config user.name --format json` now prints `fix: demo config get user.name --json`. This happens when one command below the group takes arguments, or when the words fit the arguments of exactly one of them: `config user.name` fits `get <key>` and not `set <key> <value>`. When two fit, nothing is guessed. A flag is never read as an argument.
  - **An unknown-option fix is the whole corrected command line.** `demo config get user.name --format json` now prints `fix: demo config get user.name --json`, not `fix: --json`. A near miss keeps its value (`--nmae=ada` becomes `--name=ada`), and words a shell needs quoted are quoted.

  The façades are unchanged: commander 1360/1360, yargs 816/816. The core entry is 19 bytes heavier, and `./help` is 105 bytes heavier. Both are inside their budgets.

## 0.22.1

### Patch Changes

- [#870](https://github.com/ofri-peretz/burgee/pull/870) [`54d3fd6`](https://github.com/ofri-peretz/burgee/commit/54d3fd6d199c32b2965391b1df0e2d631ff318ca) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `--version` reports the CLI's own version when it runs through the bin link npm installs. It looked up the owning `package.json` from the link's directory, so `node_modules/.bin/burgee --version` printed the installing project's version and `npx burgee --version` printed "no version declared". The same applied to every CLI built with `defineProgram` that takes its version from `package.json`.

## 0.22.0

### Minor Changes

- [#866](https://github.com/ofri-peretz/burgee/pull/866) [`4f01ff0`](https://github.com/ofri-peretz/burgee/commit/4f01ff055713076e19f67e266769c0ac2683b63e) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee migrate` fixes five findings from a trial on two real CLIs (D-20261008-migrate-u12-findings):

  - **Mocks move with the imports they mock.** The first argument of `vi.mock`, `vi.doMock`, `vi.unmock`, `vi.doUnmock`, `vi.importActual`, `vi.importMock`, `jest.mock`, `jest.doMock`, `jest.unmock`, `jest.requireActual`, `jest.requireMock`, `jest.unstable_mockModule` and `require.resolve` is now rewritten like an import, type arguments included. A `vi.mock('chalk')` left behind mocked a module nothing loaded any more.
  - **The install command is pinned.** `next` prints each family package at a caret range of the version that carries the graded drop-in, `roundel@^1.0.0` rather than `roundel`, read from the packages' manifests at build time. A project that sets `minimumReleaseAge` (`pnpm-workspace.yaml`) or `minimum-release-age` (`.npmrc`) is told so under `releaseAge`.
  - **You choose what moves.** New `--only <lib,…>` and `--skip <lib,…>` flags take incumbent package names. By default only the incumbents `package.json` declares (in any of its four dependency fields) are rewritten; one imported without being declared is listed under `undeclared` and left alone. An unknown name is a usage error, exit 2.
  - **An incumbent moves in every file or in none.** When one of its imports is refused or kept, it is listed under `held` and rewritten nowhere, so a program never runs on two copies of it. An incumbent another declared dependency still depends on is listed under `transitive`, and imports of the error classes that dependency still throws stay on the incumbent.
  - **The report reads as text.** The human report is sentences and aligned lines instead of one-line JSON, and its first line, also `summary` in `--json`, says `complete: …`, `partial: N files rewritten, M refused` or `nothing to rewrite`. The exit codes are unchanged.

  The engine's text surface for a result that is not a string moved to its own lazily loaded chunk, which also prints a result's own text when it carries one under `Symbol.for('burgee.text')`; `--json` is unchanged.

## 0.21.1

### Patch Changes

- [#857](https://github.com/ofri-peretz/burgee/pull/857) [`d80b2d0`](https://github.com/ofri-peretz/burgee/commit/d80b2d0f4a535400c6825b42ac2d8e1be2827f4e) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - The `--json` envelope's `ok` now agrees with the exit code. A command whose result names a non-zero `exitCode` printed `"ok":true` and then exited non-zero, so `burgee check <file> --json` said `ok` about a plugin it refused and `burgee migrate --json` said `ok` about a run with refusals. Both now print `"ok":false`, with the report still in `data`: `data.refused` (code, message, fix) for `check`, `data.refused[]` for `migrate`. A result with no `exitCode`, or `exitCode: 0`, prints `"ok":true` as before.

- [#847](https://github.com/ofri-peretz/burgee/pull/847) [`6d3eda2`](https://github.com/ofri-peretz/burgee/commit/6d3eda268a7368acf9051ed31564813a2ac31c38) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee migrate` reads dotenv 18.0.6 as the graded release of `seniority/dotenv` (181 / 181, control 181 / 181).

- [#848](https://github.com/ofri-peretz/burgee/pull/848) [`6ae533e`](https://github.com/ofri-peretz/burgee/commit/6ae533e4610c32bad557f5d74a24d0c9a0f07f7e) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - The plugin host refuses a hook `filter` that is not `{ command: RegExp }` when the plugin is registered. Until now a string `command` was accepted, reported by `burgee check` as "commands matching deploy", and threw a `TypeError` on the first run of any command. A bare RegExp used as the whole filter has no `command`, so its hook fired for every command. A contributed command's refusal now carries the edit to make as its `fix`, taken from the refusal itself (`declare read_only, idempotent, non_idempotent — or withheld, …`), where it used to give one sentence for every command. A plugin with no `contract` is told to add `contract: 1`. The README now shows a whole plugin as a default export, the `check --json` document with `data.name`, `data.commands` and `data.hooks[].stage`, the shape of a refusal, and how to build and run `check` from a clone.

- [#853](https://github.com/ofri-peretz/burgee/pull/853) [`86d746f`](https://github.com/ofri-peretz/burgee/commit/86d746f398911b655a6f82a77615fb79c6c326c4) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - The plugin host's hook refusals are now a single refusal, `<stage> is not { handler, filter?: { command: RegExp } }`, and its fix shows that shape. It covers a missing handler, a function or an array where the hook object should be, a string `command` and a bare RegExp used as the filter. A contributed command whose refusal carries no separate remedy now gets its own message as the fix. The core bundle goes from 24,431 back to 24,260 bytes, under the 24,282 ceiling that [#848](https://github.com/ofri-peretz/burgee/issues/848) crossed.

- [#865](https://github.com/ofri-peretz/burgee/pull/865) [`85dfea9`](https://github.com/ofri-peretz/burgee/commit/85dfea950dd4d743f5b074380a38d56fc5cd2d5b) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Refusals in a native burgee program now name the command to run, so an agent no longer has to spend a turn working it out.

  - **An unknown command lists the commands that run, with what each takes.** If they fit in the eight rows, a group's refusal lists `config get <key>` rather than `config`. A larger tree still lists one level, now also with arguments.
  - **A word that exactly names a deeper command is corrected to that command.** `get user.name` gets `fix: demo config get user.name`. Before, the fix pointed at `greet`, two edits away. When two deeper commands share the word, nothing is guessed.
  - **The fix asks for JSON in burgee's spelling.** A JSON request typed before the command (`--json config get k`, `--format json …`), or spelled as `--format json` or `--output=json`, is moved into the fix as `--json`, before any `--`. An unknown `--format json` or `--output json` on a command now suggests `--json`. `--json` is also a candidate for near misses such as `--jsno`.
  - **Help lists each command with its arguments**, the way commander does: `get <key>`, not `get`.
  - **A missing required argument no longer adds "run --help to see what it takes".** The refusal already prints the command's usage line.

  The façades are unchanged. The core entry is 66 bytes lighter, and `./help` is 54 bytes heavier, inside its budget.

- [#848](https://github.com/ofri-peretz/burgee/pull/848) [`6ae533e`](https://github.com/ofri-peretz/burgee/commit/6ae533e4610c32bad557f5d74a24d0c9a0f07f7e) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - The family `schema.json` describes what five values look like. `contract` is `1`, and burgee refuses a plugin that declares none. A caique widget's `static(spec)` gets `{ kind, message, ...sample.done }`. A seniority `rank` sits between the built-in layers at flag 0, environment 10, config file 20, `package.json` 30 and default 40. A burgee hook's `filter` is `{ command: RegExp }`, now with `command` required, so the schema and the host refuse the same filters.

- [#857](https://github.com/ofri-peretz/burgee/pull/857) [`d80b2d0`](https://github.com/ofri-peretz/burgee/commit/d80b2d0f4a535400c6825b42ac2d8e1be2827f4e) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - The family `schema.json` closes a bellpull resolver's `when` with `additionalProperties: false`, so the schema and bellpull's own validation refuse the same unknown keys.
- Updated dependencies [[`d80b2d0`](https://github.com/ofri-peretz/burgee/commit/d80b2d0f4a535400c6825b42ac2d8e1be2827f4e), [`6ae533e`](https://github.com/ofri-peretz/burgee/commit/6ae533e4610c32bad557f5d74a24d0c9a0f07f7e), [`d80b2d0`](https://github.com/ofri-peretz/burgee/commit/d80b2d0f4a535400c6825b42ac2d8e1be2827f4e), [`6ae533e`](https://github.com/ofri-peretz/burgee/commit/6ae533e4610c32bad557f5d74a24d0c9a0f07f7e), [`6aab9c5`](https://github.com/ofri-peretz/burgee/commit/6aab9c5f2e3b3c5cd551b723022952660d681f16), [`6d3eda2`](https://github.com/ofri-peretz/burgee/commit/6d3eda268a7368acf9051ed31564813a2ac31c38)]:
  - bellpull@1.0.1
  - closeout@1.0.1
  - linegauge@1.0.5
  - roundel@1.0.1
  - seniority@1.0.0

## 0.21.0

### Minor Changes

- [#839](https://github.com/ofri-peretz/burgee/pull/839) [`7694faa`](https://github.com/ofri-peretz/burgee/commit/7694faa1328fb5db10eeea8ffc7b074ca667f82e) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee migrate` reads ink 8.0.0 as the graded release of `controlroom/ink` (1304 / 1304, control 1303 / 1304) and knows ink 8's export names. A project on ink 6 is now listed under `offMajor` and left alone, because ink 6 is graded (540 / 584) but not claimed.

## 0.20.0

### Minor Changes

- [#828](https://github.com/ofri-peretz/burgee/pull/828) [`8118d5c`](https://github.com/ofri-peretz/burgee/commit/8118d5c8754a09a61c8b050169d9515121908591) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `seniority/dotenv` now follows dotenv 18, graded by dotenv 18.0.5's own suite at 179 / 179, level with dotenv itself (it was 106 / 141 against 17.4.2). `config()` takes its defaults from `DOTENV_PATH`, `DOTENV_ENCODING`, `DOTENV_QUIET`, `DOTENV_DEBUG`, `DOTENV_OVERRIDE` and `DOTENV_FAST`, or their older `DOTENV_CONFIG_*` names. It reports `◇ injected env (n) from <paths>` on `console.error` unless quiet, and its debug lines behind `┆` on `console.log`. `parse(src, { fast: true })` is dotenv's character scanner, and the regular-expression parser now expands `\n` in a value that opens with a double quote even when the quote never closes, as dotenv does. `configDotenv` is exported. Two entries are new: `seniority/dotenv/config` (`import 'dotenv/config'`, quiet unless asked) and `seniority/dotenv/cli` (`dotenv run`, with signal forwarding). `.env.vault`, `DOTENV_KEY` and `decrypt` are not built, because dotenv 18 removed them (D-20261001-seniority-dotenv-vault).

  `burgee migrate` now rewrites `dotenv` to `seniority/dotenv`, and `dotenv/config` and `dotenv/config.js` to `seniority/dotenv/config`, on dotenv 18. A project on dotenv 17 is left alone and listed under `offMajor`: 17's own suite grades the drop-in 107 / 141, because the façade speaks 18.

### Patch Changes

- Updated dependencies [[`1945d65`](https://github.com/ofri-peretz/burgee/commit/1945d65f22aafabd380d67f1e40341d6ef3aa6fa), [`1945d65`](https://github.com/ofri-peretz/burgee/commit/1945d65f22aafabd380d67f1e40341d6ef3aa6fa), [`1945d65`](https://github.com/ofri-peretz/burgee/commit/1945d65f22aafabd380d67f1e40341d6ef3aa6fa), [`8118d5c`](https://github.com/ofri-peretz/burgee/commit/8118d5c8754a09a61c8b050169d9515121908591)]:
  - bellpull@1.0.0
  - closeout@1.0.0
  - roundel@1.0.0
  - seniority@0.8.0

## 0.19.0

### Minor Changes

- [#827](https://github.com/ofri-peretz/burgee/pull/827) [`cd34546`](https://github.com/ofri-peretz/burgee/commit/cd345466edf47327be61a469eba5add35e1da2a2) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee migrate` reads the new graded releases: boxen 9.0.0 (`flagstaff/boxen`, level), dotenv 18.0.5 and `@inquirer/core` 12.0.4. A project on boxen 8 or dotenv 17 is now listed under `offMajor` and left alone, because those majors are no longer the ones graded.

## 0.18.0

### Minor Changes

- [#816](https://github.com/ofri-peretz/burgee/pull/816) [`5230016`](https://github.com/ofri-peretz/burgee/commit/52300169a98ece41b3544e5316833464e63a7c83) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee migrate` moves ink to `controlroom/ink` now that the drop-in is level with ink's own suite (584 / 584), and its `next` command installs `react-reconciler` beside `controlroom`: ink brought the reconciler in itself, and the drop-in takes it as an optional peer.

### Patch Changes

- [#816](https://github.com/ofri-peretz/burgee/pull/816) [`5230016`](https://github.com/ofri-peretz/burgee/commit/52300169a98ece41b3544e5316833464e63a7c83) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - controlroom hosts plugins (R10): `keymaps` and `panes` register through `controlroom/plugin`'s `register()` against the family schema, a screen takes either by name, and `controlroom check <plugin-file>` reports what a plugin contributes. The family schema every host ships gains the `keymaps` and `panes` definitions.
- Updated dependencies [[`5230016`](https://github.com/ofri-peretz/burgee/commit/52300169a98ece41b3544e5316833464e63a7c83), [`5230016`](https://github.com/ofri-peretz/burgee/commit/52300169a98ece41b3544e5316833464e63a7c83)]:
  - closeout@0.7.0
  - bellpull@0.5.2
  - linegauge@1.0.4
  - roundel@0.6.3
  - seniority@0.7.2

## 0.17.2

### Patch Changes

- [#804](https://github.com/ofri-peretz/burgee/pull/804) [`385f2d9`](https://github.com/ofri-peretz/burgee/commit/385f2d910489c12be205238cc0153e18cab12ebe) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - compat-oracle grades two new incumbents: Ink's own suite at 6.8.0 (593 cases, plus 148 on the internals line) and `@inkjs/ui`'s at 2.0.0 (103 cases), each with a control run against the real package. Both target the `controlroom` root and read 0 until `controlroom/ink` exists. `@inkjs/ui` is graded the way `controlroom` will ask users to run it: unmodified, with `'ink'` resolved to the target.

  `burgee migrate` now reports `ink` as a graded drop-in path that is not level yet (`controlroom`, 0 / 593), and never rewrites it.

- [#809](https://github.com/ofri-peretz/burgee/pull/809) [`4f45dbf`](https://github.com/ofri-peretz/burgee/commit/4f45dbf339ee02e4c7721b0099b8b3f486bb86f3) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `controlroom/ink`: a drop-in for `ink` 6.8 — `render`, `renderToString`, `Box`, `Text`, `Static`, `Transform`, `Newline`, `Spacer`, every ink hook and `measureElement` — rendered by the program's own React through React's own reconciler (React 18 and 19), and laid out by a TypeScript port of yoga's flexbox for the props ink exposes, with no yoga. `react` and `react-reconciler` are optional peers: installed alone, the subpath refuses on first import with `E_PEER_MISSING` and `npm install react react-reconciler` as its `fix`, and the package root never loads either. Graded by ink's own suite at 576 of 584 cases and by `@inkjs/ui`'s at 103 / 103, with `'ink'` resolved to the drop-in.

  compat-oracle resolves a target's optional peers from the suite's own tree (`Host.peers`) and can serve a gated file's internal import from the target's own module (`Host.targetInternals`); both ink rows now grade `controlroom/ink`.

  `burgee migrate` reports `ink` → `controlroom/ink` as a graded drop-in path that is not level yet, and does not rewrite it.

- [#803](https://github.com/ofri-peretz/burgee/pull/803) [`91ba281`](https://github.com/ofri-peretz/burgee/commit/91ba281bb5a82b322d779ead5e6d1f7a1dc1ec3a) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee migrate` now reports blessed, neo-blessed and terminal-kit programs. They have no drop-in, so nothing is rewritten: each screen, box, list, key, render, alternate-screen, mouse and text-input site goes under a new `guided` key in the report, with its file, line and a link to the section of that incumbent's coming-from guide. A site is reported only when its receiver came from one of the three packages in the same file, so a `screen.key(` or `.render(` on anything else is left out. The exit code is unchanged: nothing was refused.

## 0.17.1

### Patch Changes

- [#779](https://github.com/ofri-peretz/burgee/pull/779) [`ec04103`](https://github.com/ofri-peretz/burgee/commit/ec04103616b66bc1bab43f400a94c23f40358b9c) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee/yargs` follows yargs 18.2.0 and passes all 816 of its tests (real yargs: 814). With `SHELL` naming fish, `--get-yargs-completions` answers `value<TAB>description` and offers choices verbatim, and `completion` prints the fish script (`> ~/.config/fish/completions/<app>.fish`). The zsh script's `zsh_eval_context` test no longer carries a stray quote, so an autoloaded function is called rather than re-registered — the fix 18.2.0 made. The façade's bundle is 3 bytes smaller than before, fish included.

  compat-oracle's yargs suite is re-vendored at `v18.2.0` (816 tests, twelve added), and `burgee migrate` names 18.2.0 as the yargs release `burgee/yargs` was graded at.

- Updated dependencies [[`d810ac0`](https://github.com/ofri-peretz/burgee/commit/d810ac0d29ab11f04525d3394b29e83762853bcb)]:
  - seniority@0.7.1

## 0.17.0

### Minor Changes

- [#782](https://github.com/ofri-peretz/burgee/pull/782) [`4eb5f44`](https://github.com/ofri-peretz/burgee/commit/4eb5f4468892fbcaae490237b09cf17bb3690aaf) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - A failure now says what to do next. When a `USAGE` or `RUNTIME` failure carries no `fix`, stderr adds the failing command's `usage:` line and its options, with required, default, choices, relations and env noted, and the `--json` envelope carries the same thing as `error.usage: { command, options?, commands?, more? }`. The list is at most 8 rows, and `more` names the `--help` that has the rest. An unknown command lists the commands that exist and points at `--schema`. When exactly one command is near, the error's `fix` is the caller's own command line with the word corrected (`fix: tool push --target prod`). Every runnable command's help lists `--explain <option>`, and the root help ends with one `For agents:` line naming `--schema`, `--json` and `--explain`. Exit codes are unchanged. The core entry is unchanged too, at 0 bytes: the new text lives in the lazy `failure.js`, `surfaces.js`, `usage.js` and `help.js` chunks. `burgee/commander`, `burgee/yargs` and `burgee/meow` are untouched (D-20260930-failures-teach-recovery).

### Patch Changes

- Updated dependencies [[`df87199`](https://github.com/ofri-peretz/burgee/commit/df87199c8484ffaeae523dc55131f33eca485f5f)]:
  - linegauge@1.0.3

## 0.16.0

### Minor Changes

- [#783](https://github.com/ofri-peretz/burgee/pull/783) [`08976ae`](https://github.com/ofri-peretz/burgee/commit/08976ae734f0494720e0dce06dd850bf7177766f) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `ctx.interactive` is roundel's `interactive()`, the family's one rule for whether a person may be asked: a terminal on **stdin**, no `CI`, and no detected agent, with `FORCE_TTY=1` over all three. caique's prompts already ask it, so a handler and a prompt now agree about the same shell.

  It used to read stdout and ignore `CI`. Three things change for a handler that reads it:

  - Under a non-empty `CI` it is `false`, even on a pseudo-terminal.
  - With stdin piped it is `false`, even when stdout is a terminal.
  - With stdout piped and stdin a terminal (`tool deploy | tee log`) it is `true`, because an answer can still be typed.

  burgee loads `roundel/terminal` in a chunk of its own (`ctx.js`, 330 B), only on the path that runs a handler. Help, `--version`, `--schema`, `--mcp` and failures never load it. The root entry shrinks (35,629 → 35,437 B on disk), and so does the bundled initial load of `import { run } from 'burgee'` (24,297 → 24,278 B). `ctx.agent`, `detectAgent`, `AGENT_PROBES` and help's colour, which reads stdout, are unchanged. `runBurgee` forwards `tty` onto stdin too, so `tty: true` is still a terminal a person can answer on.

  The agent variables stay at five (`AI_AGENT`, `CLAUDECODE`, `CURSOR_AGENT`, `CODEX_THREAD_ID`, `GEMINI_CLI`). One joins only when it uniquely identifies an agent, so `CURSOR_TRACE_ID`, which Cursor sets in every integrated terminal, never will. roundel's `AGENTS` documents that rule, and a test pins that a person in Cursor is asked.

### Patch Changes

- Updated dependencies [[`1857ff6`](https://github.com/ofri-peretz/burgee/commit/1857ff65ca0e1b0b5686480c1a37dc8834bf688b), [`1857ff6`](https://github.com/ofri-peretz/burgee/commit/1857ff65ca0e1b0b5686480c1a37dc8834bf688b), [`08976ae`](https://github.com/ofri-peretz/burgee/commit/08976ae734f0494720e0dce06dd850bf7177766f)]:
  - bellpull@0.5.1
  - linegauge@1.0.2
  - roundel@0.6.2

## 0.15.0

### Minor Changes

- [#778](https://github.com/ofri-peretz/burgee/pull/778) [`24300f4`](https://github.com/ofri-peretz/burgee/commit/24300f42455836e73ba36daaf400c4ab2f8d1893) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `seniority`'s cosmiconfig drop-in now reads YAML the way cosmiconfig does. `.yaml`, `.yml` and extensionless rc files go through `seniority/yaml`, the package's own parser, which is loaded the first time a YAML file is read and never before. The loader used to read only the JSON subset of YAML and throw a `LoaderError` (`no YAML parser for <file>`) for the rest. It now returns what `js-yaml` 5 returns. A malformed file throws cosmiconfig's own message, `YAML Error in <file>:` followed by the reason and `(line:column)`. cosmiconfig 10.0.1's own suite grades `seniority` at 240 / 243, up from 186 / 243, level with the control's 240 / 243.

  `burgee migrate` now rewrites `cosmiconfig` to `seniority`, because the row is level. A file that imports a name `seniority` does not export, such as the type `LoaderSync`, is refused as `unknown-export` and stays on cosmiconfig. On Linux, the global config directory is still resolved from the home directory rather than from `XDG_CONFIG_HOME` (D-20260930-seniority-yaml).

### Patch Changes

- [#768](https://github.com/ofri-peretz/burgee/pull/768) [`d901bcb`](https://github.com/ofri-peretz/burgee/commit/d901bcb082af3ce748aba39dd18944b3efa769ea) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee migrate` now refuses a file that imports `@clack/prompts` and also imports, `import()`s or `require()`s `@clack/core`. Until now the file's prompts moved to `caique/clack` while its `updateSettings` from `@clack/core` kept configuring clack, which caique's prompts never read, and nothing said so. The refusal's reason is `sibling-state`, and it carries a `fix`: `import { updateSettings } from 'caique/clack' instead of '@clack/core', then re-run burgee migrate`. The file is left whole and the run exits 1. A type-only import of `@clack/core` does not refuse, and a file that imports `@clack/core` without `@clack/prompts` is left alone (D-20260930-migrate-refuses-clack-core).

- [#774](https://github.com/ofri-peretz/burgee/pull/774) [`b44f426`](https://github.com/ofri-peretz/burgee/commit/b44f426621ed799700cceda8c979de8f759f56b7) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `paratext/term-img` now takes a file path, as `term-img` does. `terminalImage('unicorn.jpg')` reads the file with `node:fs` and draws it, and a file `URL` works too. The read happens after the terminal check, so a path handed to a terminal that cannot draw it reaches your `fallback` (or `UnsupportedTerminalError`) without the file being opened. A missing file on a supported terminal throws `node:fs`'s `ENOENT`, as `term-img` does. The `Options` type is exported under term-img's name and is generic over what `fallback` returns, so a `fallback` that returns nothing type-checks.

  `paratext/term-img` now grades 18 / 18 against term-img 7.1.0's own suite, level with term-img itself. It was 12 / 18: the six cases that pass a path were refused under D-030. This supersedes D-030 for this subpath only (D-20260930-paratext-term-img-path). It is the only paratext entry that imports `node:fs`. The root `image()` still takes bytes, and a lock fails if `node:fs` reaches the root or any other entry.

  Because the row is level, `burgee migrate` now rewrites `term-img` to `paratext/term-img`.

- [#757](https://github.com/ofri-peretz/burgee/pull/757) [`b69d513`](https://github.com/ofri-peretz/burgee/commit/b69d5136ac6a49e6bf39178f73fbd89f3f4c2653) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - A flag's provenance now names the flag as it was typed: `--dry-run`, `-n` or `--no-color` in `meta.provenance` and in `--explain`, instead of the camelCase key (`--dryRun`, which burgee itself refuses). A flag that was not typed is listed in kebab-case.
- Updated dependencies [[`6195b99`](https://github.com/ofri-peretz/burgee/commit/6195b99344a21b4a05ab100fc38358deab229ce8), [`24300f4`](https://github.com/ofri-peretz/burgee/commit/24300f42455836e73ba36daaf400c4ab2f8d1893), [`8ba7c33`](https://github.com/ofri-peretz/burgee/commit/8ba7c33b8196ee9324b129a6eb25ca9daa4eeeab)]:
  - roundel@0.6.1
  - seniority@0.7.0

## 0.14.3

### Patch Changes

- [#764](https://github.com/ofri-peretz/burgee/pull/764) [`1817b62`](https://github.com/ofri-peretz/burgee/commit/1817b6286fae3943e79686a42dc635cca0f0cdda) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `caique/clack` now grades 16 / 16 against `@clack/prompts` 1.8.1's own suite, level with clack itself at 16 / 16. It was 16 / 17. The pass count did not change. The denominator did: one case, `guide.test.ts`'s `no prompt renders a guide when withGuide is globally false`, is now excluded by its exact title. It imports `updateSettings` from `@clack/core` and asserts that the prompts read that package's module state, so it grades `@clack/core` and not `@clack/prompts` (D-20260930-caique-clack-core-exclusion). The exclusion and its reason are on the compatibility page.

  Because the row is level, `burgee migrate` now rewrites `@clack/prompts` to `caique/clack`. It refuses a file that imports `box`, `progress` or `taskLog`, which `caique/clack` does not build, and leaves that file on clack. It does not rewrite `@clack/core`. So a migrated program that imports `updateSettings` from `@clack/core` is still changing clack's settings, and caique's prompts never read them. Import `updateSettings` from `caique/clack` instead.

- [#755](https://github.com/ofri-peretz/burgee/pull/755) [`ee2b2ce`](https://github.com/ofri-peretz/burgee/commit/ee2b2ce452a3c5469ebadcb637dcc23015e81d3f) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee migrate` no longer calls an incumbent removable, or suggests `npm uninstall` for it, when the only file that imports it was refused and left as it was. The dirty-tree refusal now prints its fix (`commit or stash your changes, or pass --force`) on stderr and in the `--json` envelope.
- Updated dependencies [[`e928581`](https://github.com/ofri-peretz/burgee/commit/e928581996fdeb317b4c849ae285593bfecf6b4d), [`6c2e9c5`](https://github.com/ofri-peretz/burgee/commit/6c2e9c5cee5d9962c0d75d84a766c76b76760f7f)]:
  - bellpull@0.5.0
  - linegauge@1.0.1

## 0.14.2

### Patch Changes

- [#760](https://github.com/ofri-peretz/burgee/pull/760) [`a115799`](https://github.com/ofri-peretz/burgee/commit/a1157991a5defddadfbea49ba8ea3bf161d4a832) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - chalk's graded release is 6.0.1: compat-oracle's vendored suite is re-vendored at `v6.0.1` (59 tests, one added), and `burgee migrate` names 6.0.1 as the chalk release `roundel/chalk` was graded at.

  B2 cold start also spawns `picocolors`, `roundel/tokens` and `roundel/chalk`, and gates roundel's R8 time bar — each colour entry within picocolors + 10 ms — as `cold-start-delta-ms`, the median of per-round differences.

- Updated dependencies [[`a115799`](https://github.com/ofri-peretz/burgee/commit/a1157991a5defddadfbea49ba8ea3bf161d4a832)]:
  - roundel@0.6.0

## 0.14.1

### Patch Changes

- [#723](https://github.com/ofri-peretz/burgee/pull/723) [`3e837cb`](https://github.com/ofri-peretz/burgee/commit/3e837cbd557735dd8823a54bd9f5cd03c8852221) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee dev` serves a commander program as commander again. A `Command` has a `burgee()` method too, so it was recognised as a yargs instance: a tool call ran without the injected streams, writing onto the MCP channel, and read its argv `from: 'node'`, dropping the first two words. Four code paths no input could reach are removed from the engine, the MCP server and `burgee`'s own commands, which takes 27 bytes off the core bundle; behaviour is otherwise unchanged.

- [#736](https://github.com/ofri-peretz/burgee/pull/736) [`1f9ad70`](https://github.com/ofri-peretz/burgee/commit/1f9ad70189396c701b17034a98fcd8f59fb700de) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Five fallbacks no input could reach are removed from help, the unknown-command error and the contrast check; behaviour is unchanged. Help no longer defaults a subcommand's last path word, an env name under a filter that keeps only options with one, or a wrapped description's first row, all of which are always there. The unknown-command error names the word it already read, and a field colour between two stops no longer tests for a zero-width span the loop has already stepped past.

- [#724](https://github.com/ofri-peretz/burgee/pull/724) [`063025e`](https://github.com/ofri-peretz/burgee/commit/063025e5f9ca5ae30d4987989b23ee3248ce523e) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Three code paths no input could reach are removed from `burgee/meow` and `burgee migrate`; behaviour is unchanged. `burgee/meow` no longer reads a deprecated `alias` as a spelling of its flag, because meow refuses a flag that declares one before anything is parsed. `burgee migrate` no longer falls back to an empty table for a drop-in with no export list or no supported majors, because two locks hold a table for every one.

- [#725](https://github.com/ofri-peretz/burgee/pull/725) [`8b6b1e0`](https://github.com/ofri-peretz/burgee/commit/8b6b1e04109c8dfb1bf7d623750dd3d415c996d3) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `--schema` over its budget lists each command by its declared `summary` again. `a ?? b === undefined` binds as `a ?? (b === undefined)`, so a declared summary read as true and was dropped, leaving only commands that had a description and no summary with one. The PowerShell completion script offers a camelCase option's choices after the flag as typed, `--output-format`, where it was keyed by `--outputFormat` and never matched. Code paths no input could reach are removed from completions, suggestions, the failure path, relations, config layers, the brand renderer and the test harness; behaviour is otherwise unchanged.

- [#638](https://github.com/ofri-peretz/burgee/pull/638) [`e4c1f69`](https://github.com/ofri-peretz/burgee/commit/e4c1f6951dcbc73d581ce1edce4cf3f9ae183058) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `caique/clack` now carries `@clack/prompts`' prompts, not only `limitOptions`: `text`, `password`, `confirm`, `multiline`, `date`, `path`, `select`, `selectKey`, `multiselect`, `groupMultiselect`, `autocomplete` and `autocompleteMultiselect`, with `intro`, `outro`, `cancel`, `note`, `log`, `stream`, `spinner`, `tasks`, `group`, the `S_*` glyphs, `settings`/`updateSettings` and `isCancel`, under clack's names and options. They run on caique's own keypress loop and reach nothing outside this repository. Graded by clack's own suite at 16 / 17 (was 14 / 17; the control is 17 / 17): the one case left imports `updateSettings` from `@clack/core`, which caique does not depend on (D-152). The spinner animates only on a terminal outside CI and prints each message once anywhere else. `box`, `progress` and `taskLog` are not built. `burgee migrate` reports the new grade and, since it is not level with the control, still does not rewrite `@clack/prompts`.

- [#677](https://github.com/ofri-peretz/burgee/pull/677) [`8bc14e6`](https://github.com/ofri-peretz/burgee/commit/8bc14e644f02a28ce54333d683742f2fca027917) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Measuring text against a terminal is linegauge's job, and four places did it by hand.

  - `caique/raw`: the repaint counted a frame's rows with `split('\n')` and ignored wrapping, so a choice whose hint was wider than the terminal left a stale copy of the question on screen after every keypress. It counts rows with linegauge's `lineCount` against the terminal's width, which `Writer` now carries as an optional `columns` (read through to the output stream by `createIo`). A writer without one is treated as never wrapping, as before.
  - `burgee/testing`: `stripAnsi` is linegauge's `strip`. The regex it used left private modes (`ESC[?25l`), the colon form of a truecolor SGR (`ESC[38:2::255:0:0m`) and OSC 8 hyperlinks in the text.
  - `burgee` help: descriptions and epilogues are folded by `linegauge/wrap` rather than a loop of help's own. A styled description now opens and closes its styles on each row instead of running its colour into the next row's indent, and a run of spaces at a break no longer leaves trailing whitespace. Lines the author indented are still kept verbatim, and a word wider than the row still overflows rather than breaking.
  - `burgee` `config explain`: the option column is padded in terminal columns, so a CJK option name no longer pushes its value two columns right of the others.

- [#665](https://github.com/ofri-peretz/burgee/pull/665) [`12fea8e`](https://github.com/ofri-peretz/burgee/commit/12fea8eae4d556b11dc693581cca73e16c2b633c) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Three defects carried over from the incumbents, and three places where a port answered differently from the incumbent on a bad value.

  - `burgee/yargs/parser`: with `unknown-options-as-args`, every `-`-prefixed argument ran through five flag regexes, and two of them backtracked — one quadratically, one cubically (a 4,000-character argument took ten seconds). They are linear scans now, and give the same answer as the regexes for every input, checked against them over every short string of the characters involved. yargs' own suite still passes 804 of 804.
  - `burgee/yargs/parser`: `{ "a": null }` in one config and `a.b` from a default or a second config threw "Cannot read properties of null". A `null` parent is now an absent one, as the parser's own key lookup already treated it.
  - `burgee/yargs`: `showHelp()` with an async default-command builder that rejected left an unhandled rejection that ended the process. The rejection now goes to `fail`, where yargs sends a command handler's rejection, so a `.fail()` handler receives it.
  - `burgee/meow`: `importMeta: null` throws meow's own "The `importMeta` option is required" TypeError instead of a null dereference, and `input: null` or an array is refused as meow refuses it.
  - `flagstaff/cli-table3`: a style name that cannot be read off a colour function (`caller`, `arguments`) draws the cell plain, as cli-table3 does, instead of throwing out of `toString()`.

- [#673](https://github.com/ofri-peretz/burgee/pull/673) [`5b3dafa`](https://github.com/ofri-peretz/burgee/commit/5b3dafa8c94096d59a286d13ebc06ac30d75bfa5) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee/meow` now behaves as meow 14 does in the places it did not, and meow's own suite grades it 146 / 148, level with real meow (was 132 / 148). With `allowUnknownFlags: false`, unknown flags are reported from the tokens as typed, so a declared `noAutoHelp` no longer makes `--no-auto-help` "unknown", and a subcommand's own flags are left to the subcommand. `--help` and `--version` answer only when they are the whole command line, including when the program declares them (`-h`, `-v`). The help block keeps meow's trailing blank line. Choices of the wrong type, `flags: null` and `booleanDefault: null` are refused as meow refuses them. `-F` keeps its case, `--flag ''` satisfies a required flag, `input.isRequired` receives the input alone, and `cli.pkg` is normalized lazily in the object you passed. `burgee migrate` now rewrites `meow` to `burgee/meow`.

  Its types come along too: `burgee/meow` exports meow's `Flag`, `AnyFlags`, `TypedFlags`, `FlagType`, `InputOption`, `InputOptionType` and `IsRequiredPredicate`, with the generic `Options<Flags>` and `Result<Flags>`, so `cli.flags` keeps its types after the rewrite.

- [#674](https://github.com/ofri-peretz/burgee/pull/674) [`e9f45d8`](https://github.com/ofri-peretz/burgee/commit/e9f45d85d9db5b2e3dcaa1e43f292a1281a6952a) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - README: family header, badges, install, migrating, the family table.

  Every package README now opens the same way — lockup, tagline, one badge row in one order (npm version, downloads, Quality Gate, the package's own coverage, OpenSSF Scorecard, unpacked size, dependencies, types, Node, licence, npm provenance), a row of compatibility badges read from the graded baseline — and carries the same sections in the same order: Install for npm, pnpm, yarn and bun, Quick start, Migrating as a before/after diff, Compatibility, Benchmarks, For agents, API, and a generated table of the nine packages. Links are absolute, so they work on npm as well as GitHub.

- [#678](https://github.com/ofri-peretz/burgee/pull/678) [`088cecc`](https://github.com/ofri-peretz/burgee/commit/088ceccb7dda1cbe878950c631f49f48980dd2e2) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Whether anybody is there, whether to colour, and whether a tick can be drawn are roundel's questions, and three packages answered them by hand.

  - `roundel/terminal` (new subpath, 878 B, reaching nothing): `interactive(rt)` — a terminal on stdin, no `CI`, and no agent variable (`CLAUDECODE`, `AI_AGENT`, `CURSOR_AGENT`, `CODEX_THREAD_ID`, `GEMINI_CLI`, exported as `AGENTS`), with `FORCE_TTY=1` as the override — and `unicode(rt)`, is-unicode-supported 2.1.0's table over `{ env, platform }`.
  - `caique/decide` now depends on `roundel` and asks `interactive()`. **Behaviour change:** under an agent that has a terminal — `CLAUDECODE=1` and a TTY on stdin — a missing required value is refused with a usage error naming the flag (`--x is required when nobody is there to answer`) instead of prompting and hanging the agent. `FORCE_TTY=1` now prompts even without a terminal on stdin, as it does for burgee.
  - `caique/inquirer`'s tick and `flagstaff/ora`'s log symbols and spinner fallback use roundel's `unicode()`. caique's copy was a four-condition subset: the Linux console (`TERM=linux`) now gets `√` rather than `✔`, and ConEmu/Cmder, Terminus, Alacritty, rxvt-unicode and JetBrains' terminal on Windows now get `✔`, as `figures` draws them.
  - `burgee` help colour is roundel's `colorLevel(rt) > 0`. **Behaviour changes:** `NO_COLOR` now beats `FORCE_COLOR`; `--no-color` and `--color=…` on the command line are honoured; `CLI_ACCESSIBLE` turns help colour off; and a terminal that sets no `TERM` (Windows' conhost) gets plain help unless `FORCE_COLOR`, `--color` or `COLORTERM` asks for colour.
  - `burgee/contrast` rounds with roundel's `round2`; no output changes.
  - `paratext`: the supports-color fork behind `paratext/terminal-link` is unchanged, and now held to roundel's policy by a parity test everywhere their two incumbents agree.

- [#683](https://github.com/ofri-peretz/burgee/pull/683) [`5052d67`](https://github.com/ofri-peretz/burgee/commit/5052d67489c4c58f610cf161f5cc50a0c8ef2263) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee/meow` finds the caller's `package.json` with `seniority/find-up` instead of a directory walk of its own. The answer is unchanged — the nearest `package.json` above the module that parses — and the walk is now bounded and ends on a symlink cycle.

- [#655](https://github.com/ofri-peretz/burgee/pull/655) [`4319563`](https://github.com/ofri-peretz/burgee/commit/4319563b902c9d968786196f495cf47e7d4d9d39) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - linegauge: `linegauge/slice` is graded against slice-ansi 9.0.1's own suite (104 cases, up from 15 at 7.1.2) and passes all 104; East Asian Width is Unicode 17.

  - `slice` rounds **inward** at a wide character, as slice-ansi does: a cluster the range only half covers is left out instead of returned whole. Before, `slice('あいう', 0, 3)` returned `あい` (four columns), and `truncate('あいう', 4)` returned `あい…` (five columns, over its budget). Both now stay inside the columns asked for.
  - `slice` reads the escapes slice-ansi 9 reads: `OSC 8` links ended by `ESC \` or `U+009C`, the C1 `OSC` introducer, `DCS`, `SOS`, `PM` and `APC` strings, a lone `ST`, and truncated or malformed `CSI`. A malformed `CSI` ends at the first byte that cannot belong to it, so the text after it is kept.
  - An escape inside a grapheme cluster (`e`, a style, then a combining mark) no longer splits the cluster.
  - Hyperlinks don't nest: a second open replaces the first, and the first is closed with its own introducer and terminator. A link around no visible text is removed. A close just past the end of the range is kept as written, and an opener with no text after it is dropped.
  - Where a cut lands, `slice` gives every cluster at least one position (so CRLF and zero-width characters can start or end a range) and a lone regional indicator two, as slice-ansi does. `width` is unchanged and still answers as string-width does.
  - The Wide/Fullwidth table is generated from get-east-asian-width 1.7.0 (Unicode 17), like the Ambiguous table next to it. The hand-written table was missing 1,147 code points, which `width` measured as one column where string-width measures two.

  burgee: `burgee migrate` serves slice-ansi 9 (its compatibility row moved from 7.1.2 to 9.0.1). slice-ansi 7 is still graded, at 14 of 15, but no longer claimed, so a project on slice-ansi 7 is left on it.

- [#651](https://github.com/ofri-peretz/burgee/pull/651) [`b74a24d`](https://github.com/ofri-peretz/burgee/commit/b74a24de9fa747b25aa1b405cff8958f7c42d0db) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee/yargs`: four defects carried over from yargs 18.1.0, fixed without changing an answer yargs' own suite checks (804 of 804).

  - Parsing a command string is linear. Upstream's parse-command regexes backtracked quadratically on a long run of whitespace or dots (20,000 took 0.7 s); the rewrite gives the same result for every input, checked against the original regexes over every short string of the characters involved.
  - `extends` in a config tells a path from a module name in linear time, for the same reason.
  - `pkgConf(key)` reads only a key the package.json has. `pkgConf('__proto__')` used to hand `Object.prototype` to the `extends` loader, which deletes `extends` from the object it is given.
  - zsh completions escape `\` as well as `:`. zsh's `_describe` strips one level of backslashes, so a command, option or choice containing one completed without it.

- [#681](https://github.com/ofri-peretz/burgee/pull/681) [`deffcc6`](https://github.com/ofri-peretz/burgee/commit/deffcc679cf3e97e0d2f538bc09c6810e478b80e) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee/yargs`: resolving a config's `extends` no longer deletes `extends` from the object you passed in. It reads a copy instead, so a config object is never written to while it is being resolved (CodeQL [#27](https://github.com/ofri-peretz/burgee/security/code-scanning/27)). The resolved result is unchanged, and yargs' own suite still passes 804 of 804.
- Updated dependencies [[`3250edf`](https://github.com/ofri-peretz/burgee/commit/3250edf439a45ccfd203213eddec0d9fb091e8cd), [`6d8aadf`](https://github.com/ofri-peretz/burgee/commit/6d8aadff01a4c65ef3be16fe2082b0abd0c00b90), [`ff4159d`](https://github.com/ofri-peretz/burgee/commit/ff4159d25544fd45257f145e40ff0c5f8dfc4b3a), [`5e635b0`](https://github.com/ofri-peretz/burgee/commit/5e635b0a79c16ff2b459a4d00c80d334d5d945d1), [`ff4159d`](https://github.com/ofri-peretz/burgee/commit/ff4159d25544fd45257f145e40ff0c5f8dfc4b3a), [`6ef8227`](https://github.com/ofri-peretz/burgee/commit/6ef822762f5ad19564215945d7e76aa329614585), [`7c77cd2`](https://github.com/ofri-peretz/burgee/commit/7c77cd25c8fbeea4199c38c135e3a8937907f849), [`6ef8227`](https://github.com/ofri-peretz/burgee/commit/6ef822762f5ad19564215945d7e76aa329614585), [`6ef8227`](https://github.com/ofri-peretz/burgee/commit/6ef822762f5ad19564215945d7e76aa329614585), [`e9f45d8`](https://github.com/ofri-peretz/burgee/commit/e9f45d85d9db5b2e3dcaa1e43f292a1281a6952a), [`620fc74`](https://github.com/ofri-peretz/burgee/commit/620fc74af013834ca6b15faa2772aeb94c5013b1), [`088cecc`](https://github.com/ofri-peretz/burgee/commit/088ceccb7dda1cbe878950c631f49f48980dd2e2), [`bc68493`](https://github.com/ofri-peretz/burgee/commit/bc684935589d3f3d8d5d297f292ae4ccdbb48c32), [`ee6780b`](https://github.com/ofri-peretz/burgee/commit/ee6780b4c9558de1143ff7e5983c16a71973b529), [`4319563`](https://github.com/ofri-peretz/burgee/commit/4319563b902c9d968786196f495cf47e7d4d9d39)]:
  - bellpull@0.4.3
  - closeout@0.6.0
  - linegauge@1.0.0
  - roundel@0.5.5
  - seniority@0.6.4

## 0.14.0

### Minor Changes

- [#631](https://github.com/ofri-peretz/burgee/pull/631) [`478cb96`](https://github.com/ofri-peretz/burgee/commit/478cb968212fdd814c796530155918d7e2e16fb2) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `schema` answers as an alias of `--schema` (D-151, GAPS B22). `mytool schema`, `mytool schema deploy` and `mytool schema deploy --field options.region` print exactly what the flag forms print, because `<tool> schema` is where clispec.dev and the agents that follow it look for a program's schema. A program's own meaning of the word wins: a declared `schema` command runs as written, and a root command that takes arguments receives `schema` as one. The root `--help` now lists `--schema  the program as data` among its global options. Loaded through the existing lazy `surfaces.js`; the core entry grows 14 bundled bytes.

## 0.13.2

### Patch Changes

- [#627](https://github.com/ofri-peretz/burgee/pull/627) [`4a629a9`](https://github.com/ofri-peretz/burgee/commit/4a629a9ff1129f2ce6f0c34e7cfc1d159304d18a) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Lint with every published Interlace ESLint plugin, and fix what the upgrade surfaced.

  - caique: the inquirer theme merge skips `__proto__`, `constructor` and `prototype` keys, so a theme object cannot swap the merged object's prototype.
  - burgee: last-element reads use `.at(-1)`.
  - burgee, closeout, flagstaff, roundel: helpers that capture nothing from their enclosing function move to module scope.
  - seniority: suppression comments name the `no-dynamic-require` rule that now reports the config loader's dynamic `require`.

  No public API or output changes.

- Updated dependencies [[`4a629a9`](https://github.com/ofri-peretz/burgee/commit/4a629a9ff1129f2ce6f0c34e7cfc1d159304d18a)]:
  - closeout@0.5.4
  - roundel@0.5.4
  - seniority@0.6.3

## 0.13.1

### Patch Changes

- [#604](https://github.com/ofri-peretz/burgee/pull/604) [`0e7b1e8`](https://github.com/ofri-peretz/burgee/commit/0e7b1e88a7021350cf689f109c7728f799be1589) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Each README links to its migration guides under the docs link: "Migrating from: chalk", "ora · log-update · boxen · cli-table3", and so on. That puts a path from the npm page to the guide for the library you are replacing. No code changes.
- Updated dependencies [[`0e7b1e8`](https://github.com/ofri-peretz/burgee/commit/0e7b1e88a7021350cf689f109c7728f799be1589)]:
  - roundel@0.5.3
  - linegauge@0.5.4
  - seniority@0.6.2
  - bellpull@0.4.2
  - closeout@0.5.3

## 0.13.0

### Minor Changes

- [#586](https://github.com/ofri-peretz/burgee/pull/586) [`a0c691a`](https://github.com/ofri-peretz/burgee/commit/a0c691ae6b5d3e244ddf6177238c239ece71485c) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `--format=agent` prints a command's result the way an agent wants to read it: one compact logfmt line per record — `key=value` pairs, nested keys dotted, lists of scalars comma-joined, a value quoted only when it holds a space, `=`, `"` or `,` — with no envelope, no `meta`, no summary and whitespace collapsed. A list result is one line per element; a scalar is itself. It is not JSON on purpose (oxlint's and vitest's agent reporters converged on the same shape), and it is smaller than `--json` on the same result: 31% over a representative set, from 20% on a twelve-row list to 96% on a bare count. `--json` wins when both are typed, so the envelope and D-140's failure contract are unchanged; a failure without `--json` is still prose on stderr; the exit code is the one the result names. A command that declares its own `format` option keeps the flag. The formatter loads only when the flag is typed.

- [#582](https://github.com/ofri-peretz/burgee/pull/582) [`120ba7b`](https://github.com/ofri-peretz/burgee/commit/120ba7bfb026395e691e9c50174e61741659f732) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `.burgee({ floor: true })` on the commander and yargs façades turns on the behavioural floor in one call (J3, D-121): a usage error exits 2 rather than the host's 1, and a handler that throws or rejects prints one line and exits with its E1 code rather than a stack trace (and, on yargs, the help screen). Off by default, so the hosts' own suites still pass, and it changes nothing else — a returned value is not printed, `--json` keeps its envelope, and a commander program that called `exitOverride()` keeps its exits. `--schema` from a façade program now names the reserved surfaces the program shadows, as `shadows` (J4), and `burgee/program-schema.json` describes it — and the option `negatable` flag the commander façade already printed, which the file had left out.

### Patch Changes

- [#589](https://github.com/ofri-peretz/burgee/pull/589) [`d7d9e75`](https://github.com/ofri-peretz/burgee/commit/d7d9e757d967def8a63c879b65343ca147783287) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `import 'burgee'` loads less at startup. Four things now load only when they are needed:

  - What a failed run prints (the exit-code classification, the `--json` failure envelope and the stderr message) loads only when a run fails.
  - The checks between options (`exactlyOneOf`, `conflicts`, `implies`, `dependsOn`, `exclusive`) load only for a command that declares one.
  - Everything answered without running a command (help, `--version`, `help [command]`, `completion`, `config explain`, `--schema`, `--mcp`) loads only when it is asked for.
  - Reading a config file and the `package.json` field loads only for a program that turned on config discovery.

  Output and exit codes are unchanged.

- [#594](https://github.com/ofri-peretz/burgee/pull/594) [`60c4603`](https://github.com/ofri-peretz/burgee/commit/60c46034a25fe8ca630976f6879a29e32c93884e) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee migrate` decides whether a project's commander, yargs or other incumbent is on a major it may rewrite from a declared range per drop-in (`SUPPORTED_MAJORS`), rather than from the one graded version alone. Every range is the current major today, so what `migrate` rewrites is unchanged: commander 14 and yargs 17 are now graded by their own suites (1329 / 1331 and 191 / 794) and neither grades level, so neither is claimed. The compatibility page publishes both rows.
- Updated dependencies [[`073037a`](https://github.com/ofri-peretz/burgee/commit/073037ab38b13490ab119c84122a46c7c605be14)]:
  - bellpull@0.4.1
  - linegauge@0.5.3
  - seniority@0.6.1

## 0.12.1

### Patch Changes

- [#566](https://github.com/ofri-peretz/burgee/pull/566) [`c938fbf`](https://github.com/ofri-peretz/burgee/commit/c938fbf2a4955bb0de704c4208d93c840a87f9ca) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `--mcp` holds stdout for the whole session, not only during a tool call. A timer or stream a handler left behind that printed after its reply went out still landed on the JSON-RPC transport, and a strict client stopped parsing there. Between calls, anything written to stdout now goes to stderr; replies are the only thing on the transport.

## 0.12.0

### Minor Changes

- [#481](https://github.com/ofri-peretz/burgee/pull/481) [`3a7131f`](https://github.com/ofri-peretz/burgee/commit/3a7131fc279b5964b5d193af68bc0fe81d37821f) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `config explain [command…]` is added automatically to programs that read config. It prints the precedence order (flag > env > config > package.json > default), then each option's resolved value and the source that won, including file and line. The order comes from the resolver itself, so the output always matches what a real run does. Pass `--json` for machine-readable output. A program that defines its own `config explain` keeps it.

- [#472](https://github.com/ofri-peretz/burgee/pull/472) [`c992bf2`](https://github.com/ofri-peretz/burgee/commit/c992bf2536ba3ad0c55f45a41167cc9b4be026ec) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `defineError({ name, code })` declares an error class with its own exit code (7–125). Throw it from a handler and the program leaves with that code, printing the message and any `hint` and `fix` the same way `UsageError` does, with `error.code` in the JSON envelope. Subclasses inherit the code. Defining a second class with the same code throws when the module loads.

- [#478](https://github.com/ofri-peretz/burgee/pull/478) [`4e5054c`](https://github.com/ofri-peretz/burgee/commit/4e5054cb97ddf6a2838ffc2205ce76d8508feb0b) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Options can compute their shell completions at TAB time. Give an option `complete: (partial) => string[]`, and the generated bash, zsh, fish and PowerShell scripts call the program back for that option only. Options without a completer still complete statically from `choices`, and the program never runs for them. The callback prints nothing and exits 0 if a completer fails, so TAB never shows an error.

- [#470](https://github.com/ofri-peretz/burgee/pull/470) [`3e56073`](https://github.com/ofri-peretz/burgee/commit/3e560731b386be3429afc7ad0396bcd1c48ad9dd) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `--json=<a,b>` selects the fields of a command's result, and `--json=` lists the fields a command declares (`fields: [...]` on `defineCommand`) without running it. An unknown field is refused with the valid set in the hint. Only the `=` form takes fields, so `cmd --json name` keeps `name` a positional. Declared fields appear in `--schema`.

- [#484](https://github.com/ofri-peretz/burgee/pull/484) [`635eb8c`](https://github.com/ofri-peretz/burgee/commit/635eb8cd2dfc6954c500a67fd8f76c69fcb1031a) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - A handler can throw an error, or a plain `{ code, message, fix }` object, whose `code` names an exit code: `'USAGE'` exits 2, `'CONFIG'` 3, `'CANCELLED'` 4, `'AUTH'` 5. The message and fix print as usual. This lets caique's prompt refusals set the right exit status: a question that can't be asked without a terminal exits 2 and names the flag to pass instead, and a cancelled question exits 4, never 1. burgee still does not import caique. Any other string code, such as `ENOENT`, still exits 1.

- [#474](https://github.com/ofri-peretz/burgee/pull/474) [`1955419`](https://github.com/ofri-peretz/burgee/commit/19554194342b55f8893161f894a8c2a4df1b0f21) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - burgee plugins can hook two more stages. `parse` runs before the command is resolved: it receives argv and may return a replacement, which is how an alias plugin maps `d` to `deploy`. `shutdown` runs once as the program exits, whether the command succeeded or failed. The family `schema.json` shipped in every package now describes both stages.

- [#483](https://github.com/ofri-peretz/burgee/pull/483) [`72a8103`](https://github.com/ofri-peretz/burgee/commit/72a810352e9197fdeeb278d283c0f6ae4669d909) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee/program-schema.json` is published: a JSON Schema for the document `--schema` prints, so anyone reading a program's `--schema` can validate it. `--schema` also now includes `exitCodes`, the contract's seven exit codes by name, so a caller can branch on a code without reading prose.

- [#475](https://github.com/ofri-peretz/burgee/pull/475) [`8a7f387`](https://github.com/ofri-peretz/burgee/commit/8a7f3877936fed75121b325d66b1a78c11f737ac) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - A positional argument declared with `type: 'file'` treats `-` as standard input: the handler receives the stream as `ctx.stdin`, while the positional still reads `-`. Giving `-` to two file arguments is a usage error, because standard input can only be read once.

- [#517](https://github.com/ofri-peretz/burgee/pull/517) [`0d65c75`](https://github.com/ofri-peretz/burgee/commit/0d65c754d3b8cbb46349acb272a62e03caa27236) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee migrate` now migrates the whole family, not just commander and yargs. Every drop-in the compatibility oracle grades level with its incumbent is rewritten in the same run: chalk → `roundel/chalk`, ora → `flagstaff/ora`, string-width → `linegauge`, cross-spawn → `bellpull/cross-spawn`, signal-exit → `closeout/signal-exit` and eleven more. Drop-ins not yet level (dotenv, cosmiconfig, clack, meow, …) are reported under `partial` with their grade and left alone. The report names the family packages to add and prints `next`, the install-and-uninstall command for the package manager your lockfile names.

### Patch Changes

- [#490](https://github.com/ofri-peretz/burgee/pull/490) [`8a02d68`](https://github.com/ofri-peretz/burgee/commit/8a02d68fbf30e7837efc7f38899b1f4beb4cee69) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `bellpull/node-which` is a drop-in replacement for node-which 7: `which(cmd, opts)` returns a promise and `which.sync` runs synchronously, with node-which's `all`, `nothrow`, `path`, `pathExt` and `delimiter` options and its `ENOENT` error. It passes node-which's own test suite, 5 of 5. `bellpull/which` is unchanged: it stays bellpull's own resolution API and never reads the process.

  `require('bellpull/node-which')` returns the function with `.sync` on it, as `require('which')` does, and `burgee migrate` now rewrites `which` to it.

- [#526](https://github.com/ofri-peretz/burgee/pull/526) [`91f46ee`](https://github.com/ofri-peretz/burgee/commit/91f46ee83c839863eecd7d63fd01174087fbb815) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `--mcp` keeps stdout for JSON-RPC frames only. A tool call whose handler printed — `console.log` in a `burgee/commander` action, the common case, or a direct `process.stdout.write` — wrote onto the stream the frames go out on, so the client read `hello` between two replies as a malformed message and the tool result itself said `data: null`. During a call, stdout and the stdout-printing `console` methods are now captured and returned as a second text item after the envelope, so printed output becomes the tool result; stderr is left on stderr. Both are restored when the call settles, including when it throws, and a runner that rejects is answered as an `isError` result instead of ending the server.

- [#522](https://github.com/ofri-peretz/burgee/pull/522) [`f4be6a8`](https://github.com/ofri-peretz/burgee/commit/f4be6a8733e338bea4483992edeaa72fcddd36fd) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `require('bellpull/cross-spawn')`, `require('flagstaff/cli-table3')`, `require('burgee/yargs')`, `require('seniority/dotenv')` and `require('seniority/rc')` now return what the incumbent's `require()` does — the function, the class, the factory, the object — instead of an ES module namespace. Each exports its default as `'module.exports'`, which is what Node hands a CommonJS caller, and which yargs' own entry already does. `const spawn = require('…'); spawn(…)` threw before.

- [#495](https://github.com/ofri-peretz/burgee/pull/495) [`31efa5b`](https://github.com/ofri-peretz/burgee/commit/31efa5b5e6120eb0d7bcc70778bc38d3dd9a3d7c) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - burgee's own commands move to `program.js`; `cli.js` stays the bin and still re-exports them. Importing the definitions no longer runs the CLI.

- [#519](https://github.com/ofri-peretz/burgee/pull/519) [`77ff1cb`](https://github.com/ofri-peretz/burgee/commit/77ff1cb8e595d32bb8bddf441ae21fc61e6f247d) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - The drop-ins now export their incumbents' type names, so a TypeScript program migrates by its import alone: `roundel/chalk` gains chalk's `Color`, `ForegroundColor`, `BackgroundColor`, `Modifiers` and `Options`; `flagstaff/ora` gains `Spinner`, `PrefixTextGenerator` and `SuffixTextGenerator`; `flagstaff/boxen` gains `Options`, `CustomBorderStyle` and `Boxes`; `flagstaff/log-update`, `linegauge`, `linegauge/wrap` and `closeout/exit-hook` gain `Options`; `burgee/yargs/parser` gains `Arguments`, `Options` and `Configuration`. Types only — no runtime bytes.

- [#526](https://github.com/ofri-peretz/burgee/pull/526) [`91f46ee`](https://github.com/ofri-peretz/burgee/commit/91f46ee83c839863eecd7d63fd01174087fbb815) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - A handler that fails under `--json` is now one `{ "ok": false, "error": … }` envelope on stdout and the exit code its error names, on every front end. A `burgee/commander` action that threw under a plain `parseAsync(process.argv)` escaped as a stack trace; the native engine wrote the failure envelope to stderr with stdout empty; `burgee/yargs` let a synchronous throw or a thrown non-Error escape `parseAsync()`, filed a thrown string as a usage error, and wrote an async rejection's envelope twice under `--mcp`; and both façades exited 1 for an `AuthError` where E6 promises 5. Without `--json` a façade program run the incumbent's way behaves exactly as before — a throw is still commander's or yargs' to surface; through an injected seam (`--mcp`, `burgee/testing`) an `AuthError` now exits 5 there too.

- [#549](https://github.com/ofri-peretz/burgee/pull/549) [`d5a1b02`](https://github.com/ofri-peretz/burgee/commit/d5a1b02792e7109a9ce6c2056683a98f622b2310) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `seniority/lilconfig` grades **77 / 77** against lilconfig 3.1.3's own suite, up from 67. The difference was all in the harness: two jest semantics it didn't reproduce made ten cases fail against lilconfig itself. `burgee migrate`'s report carries the new grade.

- [#547](https://github.com/ofri-peretz/burgee/pull/547) [`ef512ea`](https://github.com/ofri-peretz/burgee/commit/ef512ea6052747390b37077e2ea3e1aa3b196e48) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee migrate` now rewrites `require()` of the incumbents that ship ESM only: ansi-escapes, chalk 6, ora 9, log-update, boxen 8, string-width, strip-ansi, wrap-ansi, slice-ansi, restore-cursor, exit-hook and terminal-link. Their own `require()` already returns a namespace, as their replacements' does, so the rewrite is exact; before, it was refused as `require-of-default`. `require('burgee/yargs/parser')` now returns the parser function, as `require('yargs-parser')` does.

- [#543](https://github.com/ofri-peretz/burgee/pull/543) [`dc1b1a7`](https://github.com/ofri-peretz/burgee/commit/dc1b1a7156f7548d7229b54b9f3d367bfda0af08) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - paratext implements `ansi-escapes`' CSI half — `cursorTo`, `cursorMove`, `eraseLines`, `clearTerminal`, `enterAlternativeScreen`, `synchronizedOutput` and the rest, byte-exact with ansi-escapes 7.3.0 — so `import ansiEscapes from 'paratext'` is a full drop-in, graded 4 / 4 by ansi-escapes' own suite (it was 1 / 4 with CSI declared `undefined`). `burgee migrate` now rewrites `ansi-escapes` to `paratext`.

- [#546](https://github.com/ofri-peretz/burgee/pull/546) [`0592441`](https://github.com/ofri-peretz/burgee/commit/0592441c9ca8f81098a4aff48f15cfb141a0bece) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `paratext/terminal-link` now links exactly where `supports-hyperlinks` 4.5.0 does. It honours `FORCE_HYPERLINK`, `--no-hyperlink` / `--hyperlink=always`, `CI`, win32 outside Windows Terminal, NETLIFY, and the incumbent's version floors for iTerm2, WezTerm, VS Code and VTE (0.50.0 segfaults on OSC 8). It also recognises kitty, alacritty, ghostty, zed, Orca and Cursor. Its previous guess disagreed with the incumbent in 30 of 55 environments. The compatibility row is now 8 / 8, so `burgee migrate` rewrites `terminal-link` imports to `paratext/terminal-link`.
- Updated dependencies [[`866b972`](https://github.com/ofri-peretz/burgee/commit/866b9724652bebea867a730b8f2ea5e0ca63f5ab), [`8a02d68`](https://github.com/ofri-peretz/burgee/commit/8a02d68fbf30e7837efc7f38899b1f4beb4cee69), [`1955419`](https://github.com/ofri-peretz/burgee/commit/19554194342b55f8893161f894a8c2a4df1b0f21), [`f4be6a8`](https://github.com/ofri-peretz/burgee/commit/f4be6a8733e338bea4483992edeaa72fcddd36fd), [`1b002e0`](https://github.com/ofri-peretz/burgee/commit/1b002e0b72f8dc1aa61020fb40c26e50949f16e7), [`77ff1cb`](https://github.com/ofri-peretz/burgee/commit/77ff1cb8e595d32bb8bddf441ae21fc61e6f247d), [`f08ff58`](https://github.com/ofri-peretz/burgee/commit/f08ff582f0a0e1a5de90d9c7ff0c9401c867380c)]:
  - closeout@0.5.2
  - bellpull@0.4.0
  - linegauge@0.5.2
  - roundel@0.5.2
  - seniority@0.6.0

## 0.11.1

### Patch Changes

- [#508](https://github.com/ofri-peretz/burgee/pull/508) [`1aae1e2`](https://github.com/ofri-peretz/burgee/commit/1aae1e2186ce88421067df5317795773419e53d0) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - The installed `burgee` command runs. `dist/cli.js` shipped without `#!/usr/bin/env node`, so `npx burgee …` and the linked bin were handed to `/bin/sh` on macOS and Linux and failed with `import: command not found`. `check:artifacts` now refuses any published bin that is missing from the pack list or does not start with the shebang.

- [#508](https://github.com/ofri-peretz/burgee/pull/508) [`1aae1e2`](https://github.com/ofri-peretz/burgee/commit/1aae1e2186ce88421067df5317795773419e53d0) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Shell completions offer only flags the parser accepts. Every declared boolean was completed with a `--no-<name>` twin, which is right for burgee's own parser and wrong under `burgee/commander`, where commander negates only what the program declared — so `--no-skip-blank`, `--color` (for a lone `--no-color`) and `--no-version` were each a TAB away and each `unknown option`. Completions now read `OptionSpec.negatable`, which the commander façade sets from the program's own declarations.

- [#508](https://github.com/ofri-peretz/burgee/pull/508) [`1aae1e2`](https://github.com/ofri-peretz/burgee/commit/1aae1e2186ce88421067df5317795773419e53d0) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - The README's MCP answer says what `--mcp` does: every runnable command declares its `effects`, `withheld` is what keeps one out of the tool list, and a `burgee/commander` or `burgee/yargs` command that declared nothing is listed as `effects: 'undeclared'` rather than left out.

- [#508](https://github.com/ofri-peretz/burgee/pull/508) [`1aae1e2`](https://github.com/ofri-peretz/burgee/commit/1aae1e2186ce88421067df5317795773419e53d0) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `--mcp` tool calls reach the program with multi-word options. `tools/call` rebuilt argv as `--<property>`, so `skipBlank` went out as `--skipBlank` and both the engine and `burgee/commander` refused it; it now sends the flag the schema advertises (`--skip-blank`), and a `false` for a boolean that defaults on goes as `--no-<name>`. Under `burgee/commander`, a lone `--no-color` is advertised as `noColor` (flag `--no-color`) instead of a `--color` commander never accepts. `run(defineCommand(…))` now keeps the command's `effects`, `examples`, `arguments` and `relations`, so a single-command program's tool carries the hints it declared and is named after the program rather than `""`. An unknown-option `fix` is spelled as the flag is typed (`--dry-run`, never `--dryRun`). `OptionSpec` gains `negatable?: boolean` — `false` refuses `--no-<name>`.

- [#508](https://github.com/ofri-peretz/burgee/pull/508) [`1aae1e2`](https://github.com/ofri-peretz/burgee/commit/1aae1e2186ce88421067df5317795773419e53d0) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - The README's "Start here" runs. The quickstart omitted `effects`, which `defineCommand` requires of every runnable command, so the first thing a new user pasted threw `command "greet" is runnable and declares no effects`; its `--json` line also left out the `meta` the envelope carries. The shape test now runs the snippet and its transcript straight from both READMEs instead of from a private copy.
- Updated dependencies [[`1aae1e2`](https://github.com/ofri-peretz/burgee/commit/1aae1e2186ce88421067df5317795773419e53d0)]:
  - bellpull@0.3.1
  - closeout@0.5.1
  - linegauge@0.5.1
  - roundel@0.5.1
  - seniority@0.5.1

## 0.11.0

### Minor Changes

- [#507](https://github.com/ofri-peretz/burgee/pull/507) [`b8e97dc`](https://github.com/ofri-peretz/burgee/commit/b8e97dcb64772e413f0b6f9e17e063c73314d242) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Runs on Node 20 and 22, not just 24+: `engines.node` is now `^20.19.0 || >=22.13.0`. Those are the first releases where `require(esm)` loads without a warning, so the CommonJS `require()` path keeps working. Every package's test suite runs on exactly 20.19.0 and 22.13.0, on Linux, macOS and Windows. caique's prompts no longer call `Promise.withResolvers`, which Node 20 doesn't have.

### Patch Changes

- [#505](https://github.com/ofri-peretz/burgee/pull/505) [`9800b43`](https://github.com/ofri-peretz/burgee/commit/9800b43d9c74a49dfb66d04a40fd0d1c48892e20) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Docs: the README says "no dependency outside the burgee family" instead of implying none at all — burgee declares five, every one of them a sibling. The `zero-dependency` keyword is now `no-external-dependencies`.

- [#506](https://github.com/ofri-peretz/burgee/pull/506) [`891e132`](https://github.com/ofri-peretz/burgee/commit/891e132c4b1d8fe3001123014ea977c8ab30e973) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee/yargs` exports yargs' types — `Argv`, `Arguments`, `ArgumentsCamelCase`, `CommandModule`, `CommandBuilder`, `Options`, `PositionalOptions`, `InferredOptionTypes`, `MiddlewareFunction` and the rest of `@types/yargs`' ESM surface — and its default export is typed as a factory returning `Argv`, so a typed chain infers `argv` and an instance passes wherever a program says `Argv`. `burgee/commander` adds `OptionValues`, `OptionValueSource`, `HelpConfiguration` and `ParseOptionsResult`, `opts<T>()` / `optsWithGlobals<T>()` are generic as in commander, and its `OutputConfiguration` takes any subset. `burgee migrate` now checks every name an import asks for against what the façade exports: a type-only import of a name it lacks stays on the incumbent and is reported under `kept`, and any other is refused as `unknown-export`.
- Updated dependencies [[`9800b43`](https://github.com/ofri-peretz/burgee/commit/9800b43d9c74a49dfb66d04a40fd0d1c48892e20), [`b8e97dc`](https://github.com/ofri-peretz/burgee/commit/b8e97dcb64772e413f0b6f9e17e063c73314d242)]:
  - bellpull@0.3.0
  - closeout@0.5.0
  - linegauge@0.5.0
  - seniority@0.5.0
  - roundel@0.5.0

## 0.10.0

### Minor Changes

- [#476](https://github.com/ofri-peretz/burgee/pull/476) [`23e8b35`](https://github.com/ofri-peretz/burgee/commit/23e8b353b0d3ac8569782ee1712c8f6e9004a1e4) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `--schema <command> --field <path>` returns a single field of a command's schema, such as `--field options.region`, so an agent can read the part it needs without loading the whole document. An unknown path step is refused with the valid fields at that level listed.

### Patch Changes

- Updated dependencies [[`69563d1`](https://github.com/ofri-peretz/burgee/commit/69563d1fb14d9a4b29364446bae2fc48d86f6103), [`2dc573f`](https://github.com/ofri-peretz/burgee/commit/2dc573f884e7a4cc46829cd8f2c949a17f07710c)]:
  - closeout@0.4.0
  - linegauge@0.4.3

## 0.9.2

### Patch Changes

- [#465](https://github.com/ofri-peretz/burgee/pull/465) [`acf98f3`](https://github.com/ofri-peretz/burgee/commit/acf98f3e612c6d79e6c2b78a847abcd06a063cbc) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Each README now opens with the incumbent it replaces and the agent surface it serves (`--json`, an agent event, or a static projection), so npm shows both above the fold. README text only; no code changed.
- Updated dependencies [[`acf98f3`](https://github.com/ofri-peretz/burgee/commit/acf98f3e612c6d79e6c2b78a847abcd06a063cbc)]:
  - roundel@0.4.2
  - linegauge@0.4.2
  - seniority@0.4.2
  - bellpull@0.2.2
  - closeout@0.3.2

## 0.9.1

### Patch Changes

- [#454](https://github.com/ofri-peretz/burgee/pull/454) [`b4584e7`](https://github.com/ofri-peretz/burgee/commit/b4584e719bc0064b294aab5ea6da1c11f698f0e9) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Every package's npm `homepage` now points at its page on the docs site, `https://burgee.interlace.tools/docs/packages/<name>`, and each README links it under the header. The keywords add what people and models search for: `burgee` gains `cli-framework`, `argument-parser`, `subcommands`, `json-schema`, `mcp-server`, `model-context-protocol`, `ai-agent`, `llm`, `shell-completion`, `typescript`, `zero-dependency`, `commander-alternative` and `yargs-alternative`; the other eight gain `agent`, `ai-agent`, `non-tty`, `json` and `zero-dependency` where the package does that — `zero-dependency` only on the six that install nothing at all.

  `burgee`'s README gains a short FAQ (commander alternative, agent use, MCP, dependencies) and states the compatibility counts the oracle holds — 1,360 / 1,360 of commander's tests and 804 / 804 of yargs' — where it had said 1,215 and 1,185. `caique`'s README no longer calls a released package pre-release.

- [#442](https://github.com/ofri-peretz/burgee/pull/442) [`bdaf364`](https://github.com/ofri-peretz/burgee/commit/bdaf364f81564c1700cf1adec18f927afe6c60c9) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Every package now lists `plugin`, `plugins` and `extensible` in its npm keywords, because every package takes plugins through one shared contract.

  A plugin is a plain object, validated against the `schema.json` that ships in every package, and checked with the package's own `check` command. Each package reads its own key and ignores the rest, so one object can extend any subset of the family. The [plugins page](https://github.com/ofri-peretz/burgee/blob/main/apps/docs/content/docs/plugins.mdx) has a nine-layer example that every package's `check` accepts in CI.

- [#435](https://github.com/ofri-peretz/burgee/pull/435) [`7888524`](https://github.com/ofri-peretz/burgee/commit/78885245eb292cd4a40541fe09382a198c9c45cf) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `schema.json` now describes every plugin host in the family.

  The one schema each package ships as its plugin contract used to cover only four hosts: roundel's `tokens`, flagstaff's `glyphs`, `spinners`, `borders` and `components`, paratext's `capabilities`, and linegauge's `widths`. Five hosts validated their keys in their own code, but the file an author (or a model) writes against said nothing about them. It now describes all of them:

  - bellpull `resolvers`, including the absolute-path rule on `paths`
  - caique `widgets`
  - closeout `handlers`, including the phases a plugin may use
  - seniority `sources`, including the rank bounds
  - burgee `commands`, `hooks` and `enforce`

  Where the schema can express a rule, it gives the same verdict as the host's own validator, and a test holds the two together. Function-valued fields (`static`, `run`, `read`, `handler`) are described and required, but not typed, because JSON Schema can't say "function".

  **flagstaff** now validates a plugin against only its own keys, not the whole family schema. It no longer refuses a plugin over another host's key, which lets one plugin object contribute to several hosts. Its entry points are also 4.7–5.9 KB lighter for it.

- Updated dependencies [[`b4584e7`](https://github.com/ofri-peretz/burgee/commit/b4584e719bc0064b294aab5ea6da1c11f698f0e9), [`bdaf364`](https://github.com/ofri-peretz/burgee/commit/bdaf364f81564c1700cf1adec18f927afe6c60c9), [`7888524`](https://github.com/ofri-peretz/burgee/commit/78885245eb292cd4a40541fe09382a198c9c45cf), [`dac303e`](https://github.com/ofri-peretz/burgee/commit/dac303e944e889ac4175ac38c94e4ca0f0ca5358)]:
  - bellpull@0.2.1
  - closeout@0.3.1
  - linegauge@0.4.1
  - roundel@0.4.1
  - seniority@0.4.1

## 0.9.0

### Minor Changes

- [#421](https://github.com/ofri-peretz/burgee/pull/421) [`db3c59e`](https://github.com/ofri-peretz/burgee/commit/db3c59e3dcd373c7e6e4a057715adb173766523f) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `ExitCode.AUTH` — a refused credential gets its own code (E6).

  `RUNTIME` is the code for everything: _it failed, read the message_. A caller — a script, a
  retry loop, an agent — cannot branch on it, so a 401 and a null-pointer look identical from
  outside and a retry on one is a retry on both, forever.

  ```ts
  import { AuthError } from "burgee";

  throw new AuthError(
    "the registry refused the token",
    "the token has expired",
    "mytool login",
  );
  // exit 5, and on --json: { ok: false, error: { code: 5, message, hint, fix } }
  ```

  `AUTH` says _get a credential and run it again_, which is a different action from `USAGE`'s
  _fix the script_ and `CONFIG`'s _fix the runner_. The requirement calls it "the most actionable
  single code in the survey"; it was the one the taxonomy was missing.

  **5, where `gh` uses 4.** Four is `CANCELLED` here and has been since the contract was written,
  and moving a published code to match a neighbour's is a breaking change for everyone already
  branching on it. `aws` v2 uses 252/253/254 and agrees with nobody either — what matters is that
  the code is stable and documented.

  `fix` is the line a caller runs where `hint` is the prose a person reads, and both reach the
  `--json` envelope, so an agent never has to parse the message.

  374 bytes on the core entry.

- [#412](https://github.com/ofri-peretz/burgee/pull/412) [`4b64f6a`](https://github.com/ofri-peretz/burgee/commit/4b64f6ac6b90a5f3d6444a6f6a1731dd3fdd296f) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee/meow` — meow's surface, over burgee.

  `import meow from 'burgee/meow'` takes the place of `import meow from 'meow'`: the options
  object, the flags contract (`type`, `default`, `shortFlag`, `aliases`, `choices`,
  `isRequired`, `isMultiple`), `commands`, the help and version blocks with `autoHelp` and
  `autoVersion`, `showHelp`/`showVersion`, and the `input`/`flags`/`unnormalizedFlags`/`pkg`
  result. Graded by meow's own suite at **132 / 148 (89.2%)** against a control of 146 / 148.

  meow is one function over `yargs-parser`, and burgee already ships its own for
  `burgee/yargs`, so this takes no new dependency into the tree. The entry costs 59,820
  bundled bytes; upstream meow looks lighter only because it depends on `yargs-parser` rather
  than carrying it, and a caller installing meow installs both.

- [#428](https://github.com/ofri-peretz/burgee/pull/428) [`f0370b4`](https://github.com/ofri-peretz/burgee/commit/f0370b4e56e3c98a0214ac1fe4fcb1aedbeb8b16) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - A deprecation now has to name its replacement.

  ```ts
  defineCommand({ name: 'push', deprecated: 'publish', /* … */ });
  options: { legacy: { type: 'boolean', deprecated: '--force' } }
  ```

  `deprecated: true` used to produce `(deprecated)` in help and `warning: 'push' is deprecated` on
  stderr, which tells the reader to stop without saying where to go. `defineCommand`, and
  `Manifest.use()` for plugin commands, now refuse `true` and `''` on a command or any option, and
  the error says how to fix it. A named replacement already appeared in all three places:
  `(deprecated: use publish)` in help, `deprecated` in `--schema`, and `, use 'publish'` in the
  warning.

  **Breaking for anyone who wrote `deprecated: true`**: replace it with the name of what to use
  instead. Commander and yargs programs running on burgee's front-ends are unaffected. Those
  incumbents accept a bare deprecation, and the front-ends keep accepting it.

- [#424](https://github.com/ofri-peretz/burgee/pull/424) [`fb92e13`](https://github.com/ofri-peretz/burgee/commit/fb92e131039b5504b5b7398a99168760e213e1b0) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Help is coloured on a terminal, and `NO_COLOR` and `FORCE_COLOR` mean what they say.

  The engine rendered help plain everywhere. That met "no ANSI in a pipe or under `NO_COLOR`" only by
  never colouring at all, and it left `FORCE_COLOR` with nothing to override. Now one decision covers
  every help path:

  - `FORCE_COLOR` decides whenever it is set: `0` or `false` turns colour off, anything else (the
    empty string included) turns it on, even through a pipe and over `NO_COLOR`. This matches Node's
    own `getColorDepth`.
  - Otherwise help is coloured only on an interactive terminal with no non-empty `NO_COLOR` and a
    `TERM` other than `dumb`. **A detected agent is not an interactive terminal**, so Claude Code,
    Cursor and the rest still read plain help even when they have a TTY.

  Colour adds ANSI and nothing else: stripped, coloured help is byte-identical to the plain render,
  and `NO_COLOR=1` gives back the plain render exactly.

- [#415](https://github.com/ofri-peretz/burgee/pull/415) [`47b541a`](https://github.com/ofri-peretz/burgee/commit/47b541ade1977e781968bdfb94a41c2bd990b203) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - **The root barrel stops holding five modules open, and the initial load a consumer pays halves.**

  `import { run } from 'burgee'` was loading `help.ts`, `mcp.ts`, `schema.ts`, `plugin.ts`,
  `manifest.ts` and `seniority/precedence` whether or not a program read any of them, because
  `index.ts` re-exported their value half as a convenience. `execute.ts` already loaded each one
  behind an `await import()`; the barrel was the only thing keeping them on the startup path.

  Measured over the transitive closure of `import` statements — the bytes a bundler actually puts
  on a consumer's startup path:

  |                                   |   before |        after |
  | :-------------------------------- | -------: | -----------: |
  | `burgee` initial load, bundled    | 57,880 B | **28,637 B** |
  | `burgee` static graph, on disk    | 60,823 B | **42,223 B** |
  | cold start, `burgee ÷ cac`        |   2.567× |   **1.737×** |
  | modules Node loads for the import |       22 |           17 |

  **Breaking, and narrowly.** Every moved value has a subpath of its own:

  | was                                                                     | is now          |
  | :---------------------------------------------------------------------- | :-------------- |
  | `renderHelp`                                                            | `burgee/help`   |
  | `serveMcp`, `toolsOf`, `annotationsOf`, `MCP_PROTOCOL_VERSION`          | `burgee/mcp`    |
  | `schemaOf`, `commandSchemaOf`, `inputSchemaOf`, `summaryOf`, `Manifest` | `burgee/schema` |
  | `definePlugin`, `CONTRACT`, `PluginError`                               | `burgee/plugin` |
  | `resolve`, `explain`, `envName`, `screaming`, `ConfigError`             | `burgee/config` |

  **Every `type` stayed where it was.** A type re-export is erased and costs a consumer nothing,
  so the whole type surface — `Manifest` included, which is what keeps `defineProgram`'s return
  type nameable — still imports from `burgee`. A typed program that never called one of the moved
  functions needs no change at all.

  `--explain` and `--schema` also load on their own branch now rather than at import: `schema.ts`
  is 2,640 bundled bytes and `seniority`'s explain half is 1,018, and neither runs unless a reader
  asks for a document.

  This is D-093 reversed. That decision declined the split on a cold-start argument it did not
  have a number for; the number is 830 ms of ratio and 29,243 bytes.

- [#421](https://github.com/ofri-peretz/burgee/pull/421) [`db3c59e`](https://github.com/ofri-peretz/burgee/commit/db3c59e3dcd373c7e6e4a057715adb173766523f) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Every plugin host has a `check` command.

  ```bash
  npx linegauge check ./my-widths.mjs
  npx burgee check ./my-plugin.mjs --json
  ```

  PRINCIPLES 7 asks three things of an extension surface: the plugin is data validated against one
  published schema, there is a **`check` command that shows it every way it can be seen**, and the
  bar is measured. The first was built in all nine hosts; the second existed in `flagstaff` alone.
  So an author writing a plugin for any other host found out what it did by shipping it into a
  program — and a surface nobody can check is a surface nobody outside this repository can write
  against.

  Each command validates, registers, and shows what the host does with the plugin, in the host's own
  terms: linegauge measures each code point **before and after** the override, paratext shows a
  capability's `encode` **and** its `fallback`, roundel each token and what it replaced, caique each
  widget's static projection rendered with its own sample. burgee's returns a **document** rather
  than printing one, so `burgee check --json` is the form an agent that just wrote a plugin reads.

  They share one contract with the author, held identically across all nine:

  - a readable report, contribution by contribution, with **`ok` as the last line**;
  - a refusal with a code from the family's vocabulary and a `fix`, exit 1;
  - **`E_NO_CONTRIBUTION`** for a plugin that contributes nothing to this host — the schema allows
    unknown keys so one object registers everywhere, which makes a misspelled key silent, and this
    is how that typo tells on itself;
  - exit 2 with no file.

  Each host also gains an eval case measuring the one-turn claim, proved to discriminate before it
  was committed: green against a correct plugin, red against the same plugin with one field broken.

### Patch Changes

- [#421](https://github.com/ofri-peretz/burgee/pull/421) [`db3c59e`](https://github.com/ofri-peretz/burgee/commit/db3c59e3dcd373c7e6e4a057715adb173766523f) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `runBurgee` forwards `cwd`, `stdin` and TTY-ness to the engine. It did not.

  The harness built a whole `fakeRuntime` — argv, env, cwd, stdin, per-stream TTY-ness, exit,
  clock — and then passed **six of those nine** to `execute`. The other three were computed and
  dropped, which `.sdlc/intents/burgee/spec.md` records as T1 and calls _"the row most likely to
  make a test pass for the wrong reason"_. It is, and precisely:

  - **`tty: true` changed nothing.** `execute` reads TTY-ness off `opts.stdout.isTTY` and hands it
    to `detectAgent`; the harness passed a bare `{ write }`. A test asking for a terminal got the
    non-interactive floor and asserted on it happily.
  - **`cwd` changed nothing.** Config discovery starts at `io.cwd`, which fell through to
    `host.cwd()` — the _real_ process directory. A test pointing at a fixture tree was reading the
    repository it was running in.
  - **`stdin` changed nothing**, so nothing that reads it could be driven through the harness at all.

  `testing-harness-forward.test.ts` is the check and both cases were proved to fail on the
  six-field version: `interactive` read `[false, false]` for `tty: true`/`false`, and a
  `<name>.config.json` under the given `cwd` never reached the handler.

  The cost is **92 bytes** on `burgee/testing`, which is test-time only.

- [#415](https://github.com/ofri-peretz/burgee/pull/415) [`47b541a`](https://github.com/ofri-peretz/burgee/commit/47b541ade1977e781968bdfb94a41c2bd990b203) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - The MCP server and the help renderer load on the branch that uses them.

  `--mcp` serves a protocol until stdin closes and `--help` lays out prose with measured
  columns; a program that does neither should carry neither. Both are now reached through
  `await import()`, so a bundler with code splitting leaves them off the startup path.

  Measured as an entry chunk: `burgee` **58,056 → 19,540 bytes**, and `burgee/commander`
  **69,431 → 51,306**. No API changed — `renderHelp` and `serveMcp` are still exported from the
  root and still do the same thing.

  `commander`'s `--schema` deliberately stayed synchronous: `parse()` is synchronous by
  contract and a lazy import there returned a Promise nobody awaited, so the document never
  printed. The suite caught it.

- [#421](https://github.com/ofri-peretz/burgee/pull/421) [`db3c59e`](https://github.com/ofri-peretz/burgee/commit/db3c59e3dcd373c7e6e4a057715adb173766523f) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `onError` fires on the commander and yargs front ends. It did not.

  The plugin contract is three hooks, and the contract _between_ them is what makes them usable:
  `preRun` opens, and **exactly one of `postRun` or `onError` closes**. A plugin that starts a
  span, opens a file, takes a lock or writes an audit line in `preRun` has nowhere to finish it
  otherwise — and "otherwise" is every command that throws.

  The engine held that. Both façades ran `preRun → handler → postRun` as a `.then` chain, so a
  handler that threw **skipped `postRun` and never reached `onError`**: a plugin got an opening
  hook and no closing one at all. And `onError` was never fired by either façade under any
  circumstances, so a plugin declaring it was silently dead on a commander- or yargs-syntax
  program — the two drop-in front ends this package exists for, and a hook neither commander nor
  yargs can offer at all.

  `plugin-lifecycle.test.ts` holds the contract on both façades, in both directions, and all four
  new cases were proved to fail on the `.then`-only chain.

  68 bytes on `burgee/yargs`, 62 on `burgee/commander`.

- [#418](https://github.com/ofri-peretz/burgee/pull/418) [`c0fa8a3`](https://github.com/ofri-peretz/burgee/commit/c0fa8a37913fab17a6d06615b7432116b1c0e1db) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `explain` moves from `seniority/precedence` to `seniority/explain`.

  A re-export is not free across a package boundary. `explain` was exported from `precedence.ts`,
  so every program that resolved a configuration loaded `explain.js` whether or not anything ever
  explained one — **1,018 bundled bytes and one more module on the startup path** for the branch
  taken when a user asks _why did this option get that value_.

  `import { explain } from 'seniority'` is unchanged: the root barrel still exports it, from its
  new home. Only `seniority/precedence` stops re-exporting it. `burgee/config` re-exports it the
  same way it always did, and `burgee`'s engine loads it behind an `await import('seniority/explain')`
  on the `--explain` branch, which is now the only thing that pays for it.

  Measured on burgee's core entry: **28,637 → 27,552 bundled bytes**, and 22 → 21 modules for
  `import 'burgee'`.

- [#418](https://github.com/ofri-peretz/burgee/pull/418) [`c0fa8a3`](https://github.com/ofri-peretz/burgee/commit/c0fa8a37913fab17a6d06615b7432116b1c0e1db) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee/yargs` loads the MCP server on the `--mcp` branch, not at import.

  `yargs/factory.ts` imported `serveMcp` at the top of the file while the note above `#surfaces`
  said _"Completions and `--mcp` load lazily, so those two return a promise"_. The note was right
  about the shape and wrong about the fact: the branch already returns a promise, so the server
  always could have been loaded on it, and until now its **2,520 bytes sat on the startup path of
  every `burgee/yargs` program**.

      burgee/yargs, bundled     107,665 B  ->  105,240 B
      burgee/yargs ÷ yargs          0.969  ->  0.947

  The same shape as the root-barrel split, missed here because a comment said it had already been
  done. The weight lock's `./yargs` budget comes down from 256,000 to 214,800 with it — a ceiling
  41 KB above the measurement is not a ratchet.

- Updated dependencies [[`47b541a`](https://github.com/ofri-peretz/burgee/commit/47b541ade1977e781968bdfb94a41c2bd990b203), [`4d1b2b3`](https://github.com/ofri-peretz/burgee/commit/4d1b2b399cff354864d1e2e843a19fde80ef1f30), [`db3c59e`](https://github.com/ofri-peretz/burgee/commit/db3c59e3dcd373c7e6e4a057715adb173766523f), [`db3c59e`](https://github.com/ofri-peretz/burgee/commit/db3c59e3dcd373c7e6e4a057715adb173766523f), [`c0fa8a3`](https://github.com/ofri-peretz/burgee/commit/c0fa8a37913fab17a6d06615b7432116b1c0e1db)]:
  - bellpull@0.2.0
  - closeout@0.3.0
  - linegauge@0.4.0
  - roundel@0.4.0
  - seniority@0.4.0

## 0.8.0

### Minor Changes

- [#382](https://github.com/ofri-peretz/burgee/pull/382) [`0a37307`](https://github.com/ofri-peretz/burgee/commit/0a37307b01d0909753285c7ca88a2e4ef7cd4eee) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee migrate` — the mechanical path from commander or yargs to burgee.

  Every migration that actually happened shipped the codemod before the wave, not after it:
  `jest-codemods`, `pnpm import`, `biome migrate eslint`. burgee already had the strongest
  possible version of the claim — change one import and commander's own 1,360 tests still pass
  — and no path from _could_ to _did_.

  ```
  $ burgee migrate --dry-run
  files: 3
  imports: 3
  mapped: [{"from":"commander","to":"burgee/commander","imports":3,"files":3}]
  refused: []
  detected: {"declared":["commander"],"imported":["commander"]}
  dependencies: {"before":["commander"],"removable":["commander"],"after":0}
  graded: [{"host":"commander","reference":1360,"passed":1360,"rate":1}]
  ```

  It detects hosts from two independent sources that are allowed to disagree — `package.json`
  and the specifiers source actually imports — rewrites `commander`, `yargs`, `yargs/yargs`
  and `yargs/helpers` across all five specifier positions, and **refuses by file and line** on
  a deep import or a non-literal dynamic specifier, leaving that whole file untouched (D-051).
  It refuses a dirty git tree unless `--force`, writes nothing under `--dry-run`, never edits
  `package.json` (D-054), and never touches an API call site (D-053). The compat figures are
  read from `compat-oracle`'s baseline through a lock, never typed into the report.

  **Specifiers, not syntax trees** (D-050): a scan over five known positions needs no parser
  and therefore no dependency, and it is the fast choice as well as the rule-2 one. Measured
  over a generated 1,000-file tree: **the whole scan phase is 17 ms** and **the slowest single
  file 0.074 ms** against a 1 ms budget; the rest of the command is filesystem.

  The gate is `examples/demo-cli-commander`, which holds the same program written twice — once
  against `commander`, once against `burgee/commander` — and predates this feature. Migrating
  the commander variant produces the hand-written drop-in's import byte for byte.

  The engine gains one thing on its behalf, in `execute.ts`: a command's result may name an
  `exitCode`, and `emit` honours it. Before this there was exactly one success path and it left
  with `OK`, so a command could emit a document _or_ fail, never both — and an agent migrating
  a repository unattended needs the refusal list **and** the code. **162 bytes** measured
  (60,661 → 60,823 on the root entry), opt-in by naming the field. `migrate` itself is 10,878
  bytes loaded through a dynamic import and is denied to the root entry by name, so
  `import 'burgee'` never reaches it.

- [#384](https://github.com/ofri-peretz/burgee/pull/384) [`7f32875`](https://github.com/ofri-peretz/burgee/commit/7f328752e8318fefd70bf87eebcb0c05d789d607) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - A program written in commander's or yargs' own syntax now gets burgee's agent surfaces.

  `--mcp` lists every command instead of none: a façade command arrives with no `effects`
  because neither incumbent has such a concept, and the filter used to read undeclared as
  _not a tool_. It is now listed with `effects: "undeclared"` — absent from the list is
  strictly worse for a caller than present with an honest annotation. `withheld` still means
  absent.

  `tools/call` used to return **nothing at all** — the reply writer was read out of
  `_outputConfiguration` at reply time, and the first tool call replaces that so the run can
  be captured. A client waited forever. It now answers the `--json` envelope, call after call.

  `--json` works at the root of a command group and no longer swallows the operand after it,
  and a failure under `--json` is the envelope on stdout with `fix:` rather than prose on
  stderr.

  commander stays 1360 / 1360 and yargs 804 / 804 against their own suites.

### Patch Changes

- [#385](https://github.com/ofri-peretz/burgee/pull/385) [`c219e65`](https://github.com/ofri-peretz/burgee/commit/c219e65e2a4b0de1836b285c0df8e43a92c74189) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - A kebab-case option key is now refused where it is declared, instead of silently never
  reaching the handler.

  `toParseConfig` kebabs each declared name to build the flag and `canonical` camels every
  parsed key back, so the flag layer handed to `resolveLayers` is keyed camelCase while the
  specs beside it are keyed as declared. Declare `'dry-run'` and the two never meet: `--dry-run`
  parses, resolves to nothing, and the handler is given `undefined`. No error anywhere.

  Three of burgee's own commands were live instances. `burgee brand --allow-low-contrast` never
  suppressed the WCAG failure it names, `--bordure-width` was always `1.5` whatever was passed,
  and `burgee dev --no-watch` still watched. All three are fixed by spelling the key `camelCase`;
  the flags are unchanged, and `--bordure-width 7` now reaches the SVG as `stroke-width="14"`
  against the default's `3`, `--allow-low-contrast` emits, and `--no-watch` logs no reload when
  the entry is edited.

  **Breaking for a declaration, not for a command line.** `checkDefinition` refuses a key that
  does not survive `camel(kebab(key))` — `'dry-run'`, and also `URL`, whose canonical form is
  `url`. It throws through the clash message that was already there, because it is the same
  defect: two keys that meet on the command line, one of them written by `kebab()` rather than
  by the author. The engine was not taught a second spelling. Threading one through help,
  `--schema`, Fig, the env, config and package.json layers and the relation names, to reach a
  key that already has exactly one canonical form, is a larger surface than the bug.

  **No weight ceiling moved**, which is what D-073 asks for. `./plugin` had 5 bytes of headroom
  and a standalone message cost 187, so two things moved to pay for it: V5's reserved names out
  of their own loop in `checkCommand` into the pass `checkDefinition` was already making, and
  the numeric-bound check out of that loop into the spec helper beside the relation names. Both
  read better where they are now — `flag` is computed once and `kebab` is the identity on every
  reserved name, and a numeric bound is a fact about a spec rather than about a name.
  `definition.js` is 51 bytes smaller than before the check existed. `checkDefinition` now
  carries the reserved names; `checkCommand` is still the one door both callers reach.

  Found while building `burgee migrate`: it showed up only through the built binary, because
  every in-process case had been written camelCase.

- Updated dependencies [[`5a85175`](https://github.com/ofri-peretz/burgee/commit/5a85175da66df5e797446eaada1c3492cc8b8fff), [`88a6996`](https://github.com/ofri-peretz/burgee/commit/88a699645f986c6e5dcead465e3f36238f0ae77d)]:
  - linegauge@0.3.2
  - seniority@0.3.1

## 0.7.1

### Patch Changes

- [#373](https://github.com/ofri-peretz/burgee/pull/373) [`a1f1d40`](https://github.com/ofri-peretz/burgee/commit/a1f1d40b7d1e7244f3a180943b641bb3b491d256) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Stage 2's artifact is now `spec.md`, the name Anthropic's AI-Native SDLC playbook gives it, so the source comments and README sections that cite a package's own design document point at `spec.md` rather than `design.md`.

  No behaviour changes. The published tarballs do move, by two bytes per surviving reference — `design.md` is nine characters and `spec.md` is seven — so the four packages carrying a weight band were re-measured against it: linegauge 83,538 to 83,536; paratext 66,343 to 66,341; closeout 84,455 to 84,453; bellpull 86,113 to 86,107.

- Updated dependencies [[`955b979`](https://github.com/ofri-peretz/burgee/commit/955b9790560ad2e478a1abbcbe42ec2bc4ba7423), [`a1f1d40`](https://github.com/ofri-peretz/burgee/commit/a1f1d40b7d1e7244f3a180943b641bb3b491d256)]:
  - seniority@0.3.0
  - bellpull@0.1.1
  - closeout@0.2.1
  - linegauge@0.3.1

## 0.7.0

### Minor Changes

- [#332](https://github.com/ofri-peretz/burgee/pull/332) [`3ea38c3`](https://github.com/ofri-peretz/burgee/commit/3ea38c363b9f0cee9f1c1c2dae4037b047e98328) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - E5 and O5, which the design has marked `R` since it was written and which nothing implemented.

  `exit-code.ts` has declared `SIGINT: 130` with the comment _"SIGINT after the terminal was restored (E5)"_ from the first day of the contract, and `exit-code-lock.test.ts` grades that no other literal reaches an exit. Neither could see what was actually missing: **no code path produced 130 and nothing restored anything.** `grep -rn SIGINT packages/burgee/src` returned the declaration and nothing else. O5 — _"stdout is flushed before any exit path"_, yargs [#1519](https://github.com/yargs/yargs/issues/1519) and [#2118](https://github.com/yargs/yargs/issues/2118), _"No truncated JSON"_ — was the same shape one line down, against `host.exit(code)`, which is `process.exit` and truncates a pipe by definition.

  Both are now `closeout`'s, which is burgee's first dependency on it and the reason it exists: bound every exit path, run the handlers exactly once, hand the terminal back last. Writing the listener in burgee instead would have been the fourth copy of one in this repository.

  - **`ctx.onExit(handler, label?)`** — cleanup that runs on every path out of a run: a normal return, `ctx.exit`, Ctrl-C, SIGTERM, a terminal closing out from under you, an uncaught throw. It runs after stdout has drained and before the terminal is handed back, and exactly once however many of those arrive together. `label` is what a breached shutdown deadline calls it; an unlabelled arrow is reported as `(anonymous)`, and the anonymous arrow is the shape that hangs.
  - **A run that owns the process** gets closeout's full wiring — `exit`, `beforeExit`, five signals, `uncaughtException`, `unhandledRejection`. A run that injects its own `exit` — the harness, the MCP loop, every façade test — gets the same registry **detached**, with no listeners on anybody's process.
  - **Every exit now goes through one place.** `ctx.exit(code)` used to call the injected exit and then throw; on the real path the first half was `process.exit`, so cleanup registered a line earlier could never run. It now throws only, and the failure path drains, runs the cleanup and leaves — which makes the file's own sentence, _"exactly one code path from argv to exit"_, true of the exit as well as of the parse.

  Measured: commander 1360 / 1360 and yargs 804 / 804 before and after, unchanged — the two front-ends do not reach `execute.ts`. The core entry is 51,293 → 52,683 bytes against an unchanged 53,300 budget, so nothing was ratcheted for it; `shutdown.ts` is 1,001 of those and the engine's routing is the other 389. `npm i burgee` gains closeout's 81,360 bytes unpacked, and closeout depends on nothing.

- [#361](https://github.com/ofri-peretz/burgee/pull/361) [`a0cb8ca`](https://github.com/ofri-peretz/burgee/commit/a0cb8caf22a1e1e56105cccd65fe02cab1516804) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - An error carries `fix` — the exact flag to run next — beside `hint`.

  E3 asks for _"`code`, `message`, `hint`, and where possible `fix`: **the exact command or flag
  to run next**"_. The envelope was `{code, message, hint}`, and `hint` is prose.

  The distinction matters most for the caller this package exists for. **An agent can execute a
  `fix`.** A `hint` it has to read, interpret and guess at — one more turn, and the turn where
  it invents a flag that does not exist. Every _plugin_ error in the family already carried
  `fix`; the engine's own did not.

  ```
  $ tool deploy --forc --json
  {"ok":false,"error":{"code":2,"message":"unknown option --forc",
                       "hint":"did you mean --force?","fix":"--force"}}
  ```

  `fix` is omitted, never guessed, when there is no near match: an executed guess burns the turn
  the field exists to save.

- [#361](https://github.com/ofri-peretz/burgee/pull/361) [`a0cb8ca`](https://github.com/ofri-peretz/burgee/commit/a0cb8caf22a1e1e56105cccd65fe02cab1516804) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `--help --json` prints help as data.

  It printed the same prose as `--help`. A caller who asked for a machine-readable answer got
  one they had to parse — the exact failure the whole `--json` surface exists to avoid, on the
  flag people type first. burgee's design recorded it as **F2, `Not built`**: _"no JSON help
  surface; `--help --json` prints the same prose as `--help`."_

  The document is `commandSchemaOf` scoped to the node you asked about — the same shape
  `--schema` publishes, so a reader learns it once — plus `schemaVersion`, and for a group the
  names of its children. A group's help is a menu; a reader who wants a child's detail asks for
  that child, which is the same walk they would do on the text.

  Plain `--help` is unchanged.

- [#337](https://github.com/ofri-peretz/burgee/pull/337) [`e974114`](https://github.com/ofri-peretz/burgee/commit/e974114a8da753d4fd4f97d7e79928407d82e54a) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Options can declare `dependsOn` and `exclusive`, and the declaration is enforced rather
  than documented.

  They are an **alias**, not a second engine: `exclusive` desugars to `conflicts` and
  `dependsOn` to `implies`, into the `Relation` union that already existed. Command-level
  `relations` are evaluated first and the derived entries after, so no existing command
  changes which error it reports first.

  The second spelling exists because it is the one the two incumbents use on the _option_
  rather than on the command — commander's `.conflicts()` / `.implies()` and yargs'
  `conflicts` / `implies` both hang off an option, and a drop-in that only accepts the
  command-level form is not drop-in.

  Enforced at parse time through the existing usage path: `UsageError`, exit 2, text
  `error: --out requires --force` with `hint: pass --force`, and `--json` gives exactly
  `{ok:false,error:{code:2,message,hint}}`. No new error shape.

  Refused at _definition_ time when a name is not an option of that command, or is the
  option itself. Both are silent at run time, in opposite directions: the first can never
  fire, the second always does.

  Projected three ways, because a relationship a caller cannot see is a relationship they
  will violate: `--schema` carries both spellings, help renders `(requires --force)` and
  `(conflicts with --table)` — it rendered no constraint of any kind before this — and the
  Fig spec emits `dependsOn` / `exclusiveOn`, Fig's own two keys.

- [#334](https://github.com/ofri-peretz/burgee/pull/334) [`0f00f72`](https://github.com/ofri-peretz/burgee/commit/0f00f7273ab0ca111c5869e2b08eb79314df7f70) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - burgee's plugin host now refuses a plugin it cannot host, and a plugin's commands go through
  the guards a first-party command goes through. **This is a breaking change to a published
  extension point, and it is deliberately a loud one.**

  The defect, measured rather than inferred. `definePlugin(plugin)` was `return plugin;`, and
  `Manifest.use()` pushed the plugin and called `this.add()` directly — where `defineCommand`
  enforces the reserved names of V5 and runs `checkDefinition`. So a plugin's command was
  admitted unread, and `toParseConfig` seeds `json: { type: 'boolean' }` and then writes every
  declared option over the top of it. **A plugin option named `json` therefore did not clash
  with the envelope flag; it replaced it**, on a framework whose entire agent-facing contract is
  that `--json` is machine-readable output. Four more were accepted the same way: `enforce:
'mid'` (`NaN` in the hook comparator), a plugin with no `name` (commands carried
  `plugin: undefined`, so M3 attribution was silently lost), a hook with no `handler` (a
  `TypeError` one run later, classified `RUNTIME`), and a contributed path that was already
  declared — which `find()` and `resolve()` answer differently.

  **What `contract` means, and how an old plugin fails.** `packages/burgee/src/plugin.ts` is
  now a plugin host in the sense the rest of the family means: it owns `Plugin`, `validate()`,
  `PluginError` and a `PluginErrorCode` of `E_PLUGIN_SCHEMA | E_PLUGIN_CONTRACT`, both already
  in the vocabulary home's union. `contract` is the revision of the family plugin object a
  plugin was written against, and this burgee knows `1`. A plugin that declares none is refused
  with `E_PLUGIN_CONTRACT` naming the version:

  > plugin "acme" declares no contract; burgee 0.6.1 and earlier validated none of it
  > — rebuild it against this burgee (`definePlugin` stamps `contract: 1`), or add that key by hand

  That refusal is the point rather than a side effect. An object with no `contract` was authored
  against a host that checked nothing, so the honest reading of its silence is _unknown_, not
  _fine_ — and it may be carrying exactly the `json` option above. A silent behaviour change on
  a published extension point is worse than a loud breaking one. `definePlugin` now stamps the
  contract it was compiled against, so a plugin rebuilt against this release needs no edit, and
  only objects built against the unvalidated host are refused.

  Two supporting changes. The definition-time checks moved from `validate.ts` to a new
  `definition.ts`, because the plugin host pulls them into every graph that reaches the manifest
  — including the commander and yargs front-ends, which reach nothing else of the engine.
  Importing `validate.js` whole for `checkDefinition` put 6,409 bytes of run-time coercion into
  both front-ends and took `burgee/commander` over the 128,000-byte budget that exists to prove
  it is no heavier than commander's own `lib/`; the split keeps it at 125,667. And burgee ships
  `src/schema.json`, byte-identical to the family's, exported as `burgee/schema.json`.

  Measured: `burgee/commander` 1,360 / 1,360 and `burgee/yargs` 804 / 804 against the
  incumbents' own suites, unchanged. Core costs 4,191 bytes on disk (52,959 → 57,150), priced
  per entry in `weight.test.ts`.

- [#361](https://github.com/ofri-peretz/burgee/pull/361) [`a0cb8ca`](https://github.com/ofri-peretz/burgee/commit/a0cb8caf22a1e1e56105cccd65fe02cab1516804) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - burgee's extension surface: `./plugin` is published, and `effects` is no longer optional.

  **`burgee/plugin`.** Every other host in the family publishes its plugin module at
  `<host>/plugin` — `bellpull`, `caique`, `closeout`, `flagstaff`, `paratext`, `roundel`,
  `seniority`. burgee, the package that declares the plugin shape the other seven register
  against, did not, so `scripts/plugin-contract-lock.test.ts` had to reach it by relative path
  and recorded the gap as a declared one. It is the shape `plugin-schema-lock` caught in
  flagstaff — a host whose own refusal names something the author cannot reach — and burgee's
  version was the quieter kind, because the `fix` named no specifier at all: it said _rebuild
  it against this burgee, `definePlugin` stamps the contract_, and left the author to work out
  where `definePlugin` lives. The convention the family teaches is `burgee/plugin`, and that
  threw `ERR_PACKAGE_PATH_NOT_EXPORTED`. Both halves are fixed: the subpath resolves, and the
  message says its name. `burgee/plugin` exports `CONTRACT`, `definePlugin`, `validate`,
  `PluginError`, `Plugin` and `PluginErrorCode`; the root barrel keeps the four it always
  carried, because one module behind two doors is what `burgee/yargs` and
  `burgee/yargs/helpers` already are, and `Manifest.use(plugin: Plugin)` is a root export.
  `validate()` and the `Plugin` interface are the half only the subpath carries — the host's
  vocabulary rather than a program author's.

  **`effects` is required on a command that runs — a breaking change.** Any CLI with an
  un-annotated runnable command will now fail at definition time rather than starting. The
  one-line migration: add `effects: 'withheld'` to every runnable command that declared none,
  then replace it with `read_only`, `idempotent` or `non_idempotent` on each command an agent
  should be able to call.

  It is breaking on purpose, because the old behaviour was silent. `toolsOf` serves only a
  command that declared its `effects`, and that filter is right and unchanged: an agent gaining
  shell-equivalent power over a CLI nobody meant to publish is a security posture, not a
  convenience. What was wrong is that its input had one spelling for two different things.
  _I decided agents should not have this_ and _I forgot_ both arrived as `undefined`, so the
  second shipped as the first — you released, and the tool you built for an agent simply was
  not in `tools/list`, with a shorter list than you expected as the only evidence.

  So `effects` has no default, and declining is something an author writes down:
  `effects: 'withheld'`, a fourth value of the same field. Not `'none'`, which reads as _this
  command has no effects_ — that is `read_only`, the one value it could be confused with. Not a
  second boolean field either: beside a now-required `effects` that would mean declaring what a
  command does to the world silently opts it into the tool list, and the new field's default
  would be the silence this change removes. One field, four answers, no default, and therefore
  no state in which forgetting is possible.

  The three projections then disagree on purpose, each correctly. `--schema` publishes
  `effects: "withheld"`, because an agent reading a program as data is better served by _this
  exists and is not for you_ than by a gap it cannot tell from a command that does not exist.
  `tools/list` omits it. The Fig spec and the shell completions carry it exactly as before —
  nothing in `completions.ts` reads `effects` and nothing here makes it start, because
  withholding is about agents and a person typing at a terminal is not one.

  Two limits, stated rather than implied. The refusal is on burgee's own declaration API:
  a command built through `burgee/commander` or `burgee/yargs` reaches the manifest without
  passing that door, because neither incumbent has a notion of effects and their graded suites
  declare none — commander **1360 / 1360** and yargs **804 / 804**, both unchanged by this
  release — so a façade user's command is withheld in fact and cannot be made to say so. And
  `effects` stays optional on the TypeScript type, because a field whose presence depends on a
  sibling's would mean splitting `Command` into a union at the cost of the option-spec
  inference every caller relies on; the check is at definition time, not at compile time.

  `burgee dev` is the first command in this repository to declare `'withheld'`, and not as a
  formality: `dev` **is** an MCP server, so a tool call that started it would be a second,
  never-finishing server nested inside the first, on the same pipe. `burgee brand` declares
  `non_idempotent`, because it overwrites six files in a directory the caller names.

  Weight, measured on a forced rebuild rather than a cached `dist/`: the core entry goes
  58,771 → 59,732 bytes on disk (`+961` over both changes, of which `+938` is the refusal),
  `burgee/testing` 62,992 → 63,953, `burgee/cli` 78,071 → 79,088, `burgee/commander`
  126,989 → 127,876 inside its unchanged 128,000, and `burgee/yargs` 230,869 → 231,756 inside
  its unchanged 256,000. The new `burgee/plugin` entry is 7,095 and costs a program nothing:
  `manifest.js` imports `validate` as a value because `use()` is synchronous, so every entry
  that reaches the manifest already carried those bytes.

- [#360](https://github.com/ofri-peretz/burgee/pull/360) [`61c51f9`](https://github.com/ofri-peretz/burgee/commit/61c51f99481aab65c0743077feaea2dbff39acca) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee/commander` spawns `executableSubcommand` through `bellpull`, and burgee no longer
  imports `node:child_process` anywhere.

  The gap was declared, dated, and carried its own release condition.
  `inline-implementation-lock` read: _"commander's `executableSubcommand` spawns a sub-binary
  and forwards five signals to it. Both are bellpull's job; bellpull was a seven-line
  placeholder when this was written, and the engine lane adopts it once bellpull grades
  against cross-spawn's suite."_ It grades **68 / 68**.

  What it buys a consumer is the Windows branch. Upstream commander sends **every** Windows
  spawn through `node`, because `spawn` does not search `PATHEXT` and, since the fix for
  CVE-2024-27980, Node refuses a `.cmd` without `shell: true`. That is a workaround for a
  resolution problem, and it is wrong for a subcommand that is a `.cmd`, a `.bat`, or has a
  shebang that is not node — a real program with a real sub-binary. `bellpull` resolves the
  executable, builds the `cmd.exe /d /s /c` line itself and escapes every argument, so
  nothing reaches a shell as text.

  `ChildProcess` comes from `bellpull/cross-spawn` too, which re-exports it precisely so a
  consumer does not have to name `node:child_process` for a type.

  **commander stays 1360 / 1360, ▲ 0**, measured after the wiring — which is the whole
  question, since `spawn` is mocked in roughly 23 of those cases and the earlier attempt at
  this took the row to ungradeable. `bellpull/cross-spawn` reads `spawn` off its default
  import for that reason, and this consumer reads it off the namespace at the call site.

  Cost: **+1,097 B** on `./commander`, ratcheted at the measurement.

### Patch Changes

- [#332](https://github.com/ofri-peretz/burgee/pull/332) [`3ea38c3`](https://github.com/ofri-peretz/burgee/commit/3ea38c363b9f0cee9f1c1c2dae4037b047e98328) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Two checks that grade what was previously asserted by snapshot or by fake: the Fig spec is
  checked against Fig's own vocabulary, and Ctrl+C is pressed at a real terminal.

  **`fig-schema.test.ts` — Fig publishes no schema, and that is the finding.** PLAN 2.5.3 asks
  for the emitted spec to be validated "against Fig's own schema". There is none:
  `@withfig/autocomplete-types@1.31.0` ships four files — `LICENSE`, `README.md`,
  `package.json` and `index.d.ts` — so the contract is a TypeScript namespace declaration, not
  anything a validator reads at runtime. It was last published 2024-05-08.

  So the check is structural, and the objection `fig-spec.test.ts` recorded against doing one —
  _"writing the allowed-key table from memory would be worse than not checking"_ — is answered
  by giving the table a provenance rather than by giving up. The allowed keys were extracted
  mechanically from Fig's own `index.d.ts`, recorded with the version and the file's SHA-256, the
  way `compat-oracle` vendors an incumbent's suite. **No dependency is added**: the table is
  forty strings, and the package is not installed, not in `devDependencies` and not in the
  lockfile. It reproduces Fig's own asymmetry — `Subcommand` and `Option` extend
  `BaseSuggestion`, `Arg` extends nothing and so has no `priority` and no `displayName` — which
  is the part a table written from memory gets wrong.

  Covered: every emitted key is one Fig declares, on the node type it is emitted on; `name` is
  present and is `SingleOrArray<string>` where Fig requires one; `subcommands`, `options`, `args`
  and `suggestions` have the shapes Fig declares; the whole tree is walked. Not covered, and said
  rather than implied: Fig's semantics past its key names — a `priority` outside 0–100, a
  malformed `generators` entry, a `loadSpec` naming a spec that does not exist. Nothing here
  means "this works in Fig", only "this is not obviously not a Fig spec".

  Proven red on the unfixed state: with `renderFigSpec` emitting `subCommands` — the typo the
  snapshot blessed — the case fails with `<root>: 'subCommands' is not a key Fig declares on a
subcommand`. Nine more cases prove it refuses a missing name, a name of the wrong type, a
  container that is not a list, an arg given a subcommand-only key, and a fault three levels
  down; one more proves it is not simply refusing everything.

  **`pty-signal.test.ts` — the signal path, graded through a real tty.** `shutdown.test.ts`
  raises signals on a `ProcessLike` that records, so the "signal" never leaves the test process.
  Between a keypress and a handler sits the tty line discipline, which neither that test nor a
  pipe has: in canonical mode `ISIG` turns `0x03` into a `SIGINT`, and in **raw** mode the
  identical keystroke arrives as a byte and raises nothing. A test that writes `\x03` to a pipe
  grades the raw path whatever it believes it is grading — which is how `caique` shipped a prompt
  that restored the cursor on a cancel and never on a signal, with a green suite.

  This runs burgee's built `dist/shutdown.js` on a real pty, presses Ctrl+C, and asserts the tty
  echoed `^C`, that the handler the program registered ran, and that the process **died of**
  `SIGINT` rather than calling `exit(130)` — which is the POSIX-correct outcome and not what
  `shutdown.test.ts`'s fake records: 130 is a shell's arithmetic for `128 + 2`, not an exit call.
  A program that exited 130 here would tell its parent it chose to stop.

  The pty comes from `python3`'s standard-library `pty.fork()`, so nothing enters the lockfile —
  the same borrowing as calling `git` in `compat-oracle/src/vendor.ts`. Two other dependency-free
  routes were considered: `script(1)` was measured and rejected, because BSD `script` calls
  `tcgetattr` on its own stdin and dies with `Operation not supported on socket` under any test
  runner; and `zsh/zpty`, which `scripts/complete-zsh.zsh` already uses for the zsh completion
  case, is right where the subject _is_ a shell widget but is gated on `has('zsh')` and an
  apt-install, where `python3` is preinstalled on every hosted runner. **Windows is skipped with its
  reason**, not quietly dropped: Python's `pty` is POSIX-only and a Windows pseudo-console means
  ConPTY through a native addon, so the third OS PLAN 2.5.4 asks for costs `node-pty` — a native
  build on every runner, and `compat.yml` installs with `--ignore-scripts`. That is a decision for
  a person.

  Proven red on the unfixed state: with the fixture using the engine's pre-`shutdown.ts` exit — a
  bare `process.exit(130)` on SIGINT — both cases fail, on `cleanup ran: expected '' to be
'cleaned up'` and `killed by SIGINT (2): expected +0 to be 2`.

  commander 1360 / 1360, yargs 804 / 804 and cross-spawn 68 / 68 before and after, unchanged.

- [#332](https://github.com/ofri-peretz/burgee/pull/332) [`3ea38c3`](https://github.com/ofri-peretz/burgee/commit/3ea38c363b9f0cee9f1c1c2dae4037b047e98328) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Help measured its columns with `String.length`, so a CJK or emoji command name mis-drew its own help screen.

  `.length` is the count of UTF-16 code units, which equals the number of columns a terminal draws only for the Latin-1 subset. `部署` is two code units and four columns; `🚀` is two and two. `help.ts` used it in five places — sizing the shared term column, deciding which terms overflow it, padding after a term, and both width tests inside the word wrapper — so a program whose commands are not spelled in ASCII got a description column that did not line up and description text wider than the terminal it asked for.

  `yargs/cliui.ts`, one directory over, has imported `width` from `linegauge` for exactly this job since it was ported, and its own comment records the reason: cliui's port carried its own `stringWidth`, the ITU T.416 sub-parameter form `ESC[38:2::255:0:0m` that chalk emits for truecolor left `:2::255:0:0m` behind, and a 13-column string measured 25. burgee already depended on `linegauge`. This file simply was not asking.

  - **Every measurement of rendered text in `help.ts` is now `linegauge`'s `width`**, and the term column is `widest`, which is the function that exists so a caller does not spread a large array into `Math.max`. The wrapper carries a running column count rather than re-measuring the accumulated line per word, so a long paragraph stays linear.
  - **For ASCII the two agree exactly**, which is why no graded screen moves: commander 1360 / 1360 and yargs 804 / 804 before and after, unchanged.
  - **What is still not fixed, in any character set:** a single token longer than the row is not broken. `wrap('see https://…/no/spaces now', 20)` leaves the URL on one over-long row today, `linegauge`'s own `wrap` defaults to `hard: false` for the same reason, and hard-breaking would re-draw the graded screens that contain URLs. A test pins that as a known limit rather than leaving it to be re-found.

  Help also has snapshots now (PLAN 2.5.1), which it had none of: five command shapes × the plan's three widths — 33 where the term column is clamped, 80 where the ordinary case wraps, 120 where alignment is what is on trial. A help screen is a drawing and a drawing is a contract, which is the call this repository already made for `boxen`; the renderer's by-construction fixes were each asserted once by a test that names the property it checks, and therefore could not see a change nobody was looking for.

  The core entry is 52,683 → 52,893 bytes against an unchanged 53,300 budget, so nothing was ratcheted. `linegauge` joins `closeout` and `seniority/precedence` as a bare import core admits, on the same argument as both: measuring a line is linegauge's own job the way precedence is the parser's, and the alternative here was the second copy of a width function staying wrong.

- [#343](https://github.com/ofri-peretz/burgee/pull/343) [`b245fb0`](https://github.com/ofri-peretz/burgee/commit/b245fb06db7fb796fe9e12d1f15c72adc10dd5c9) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee` declares `sideEffects`, so a consumer's bundler may drop a module nothing imports.

  Every module in the package is a declaration or a pure const except one, and that one is
  named rather than the field being set to a flat `false`: `dist/cli.js` ends in `run(program)`,
  because it is the package's own command line and executing on import is the whole point of it.
  `sideEffects: ["./dist/cli.js"]` is therefore the accurate statement, where `false` would have
  been a claim the package does not meet. `roundel` and `flagstaff` already carried the field;
  `burgee` did not, which is the only reason this is a change rather than a fact.

  Measured against the B4 fixtures, esbuild takes **9 bytes** off the core entry point
  (56,868 → 56,859) and nothing off `burgee/commander` or `burgee/yargs` — esbuild's own
  tree-shaking had already reached everything the field would have licensed it to drop. The
  field is worth more to webpack and rollup, which consult it directly and are conservative
  without it. No entry point changes shape, and every compat row is where it was: commander
  1360 / 1360, yargs 804 / 804.

- [#351](https://github.com/ofri-peretz/burgee/pull/351) [`488cbe5`](https://github.com/ofri-peretz/burgee/commit/488cbe56b8d2b0b8f6f21b252f4d9db95e290d81) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `--schema` on a yargs-shaped CLI now emits the same document as the other two front ends.

  `yargs/factory.ts` hand-rolled `JSON.stringify(schemaOf(manifest), null, 2)` where `execute.ts` and `commander/command.ts` both call `machineJson(value, head)`. The façade therefore could not see `--format=json-pretty` — the escape hatch R1 added for the person debugging a schema — and emitted the indented document unconditionally. On the fixture this change is tested against, a plain `--schema` wrote **365 bytes through yargs against 240 through the engine and through commander**: the same value, 52% more bytes, and no way to ask for either form.

  **What changes for a caller.** A yargs-shaped program's `--schema` is now compact by default, and indented only when `--format=json-pretty` is passed. Both documents parse to the same value, so a reader that parses is unaffected; a reader that diffed the raw bytes, or eyeballed the stream, will see the compact form where it used to see the pretty one.

  The cost is **+71 bytes** on `burgee/yargs` bundled (114,738 → 114,809): `machineJson` and its flag constant could previously be tree-shaken out of that entry, and now cannot. `burgee` core and `burgee/commander` are unchanged to the byte. That entry is already over `lighter-than-yargs` (1.032 → 1.033), and this makes it marginally worse on purpose — three front ends that disagree about what `--schema` means is not a weight saving, it is a defect the weight measurement was hiding.

  The property is now locked end to end rather than per writer: `machine-json.test.ts` drives one CLI definition through all three front ends and asserts the bytes are identical, in both the compact and the pretty form. The two suites that existed before were each true of a single writer in isolation, which is how three writers came to disagree.

- [#298](https://github.com/ofri-peretz/burgee/pull/298) [`ead5f01`](https://github.com/ofri-peretz/burgee/commit/ead5f016ee7fd20492a041c1e6159aea27b2ed5f) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `cliui`'s `toString()` is now linear in the cell it renders. `rowToString` ended each line
  with `str.replace(/ +$/, "")`, whose unanchored start makes the engine retry at every
  position in a run of trailing spaces; a row built from a 50,000-space cell cost 1,223 ms,
  and doubling the cell quadrupled it. The trim now scans, and the same call takes 69 ms —
  the second half of the fix that `measurePadding` got in [#278](https://github.com/ofri-peretz/burgee/issues/278). Output is unchanged: only
  U+0020 is removed, so a trailing tab still survives under `wrap: false` as it did before.

- [#332](https://github.com/ofri-peretz/burgee/pull/332) [`3ea38c3`](https://github.com/ofri-peretz/burgee/commit/3ea38c363b9f0cee9f1c1c2dae4037b047e98328) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - A ratchet on whether the family actually composes: every package except `burgee` must be used
  by another package in it.

  `layer-boundaries-lock` is the negative half of PRINCIPLES rule 14 — no package does a job a
  sibling exists to do. This is the positive half, and it is the one that was failing. Measured:
  **five dependency edges in a nine-package family**, with `caique`, `paratext`, `closeout`,
  `bellpull` and `flagstaff` used by nothing at all — and one job, putting the cursor back
  however the process dies, implemented **three times**, by three files each of which argues in
  its own comments that a second copy is the danger.

  A layer nothing else uses has never been proven to fit the stack. The split into nine packages
  is only real if the packages compose; otherwise it is a directory layout and the fit is an
  assumption.

  `edges` may only go up and `awaiting` may only shrink, each entry carrying the reason it is
  still there. A package must leave `awaiting` the moment it gains a consumer — otherwise the
  list becomes a place to park the problem, and the ratchet never notices the work was done.

- [#332](https://github.com/ofri-peretz/burgee/pull/332) [`3ea38c3`](https://github.com/ofri-peretz/burgee/commit/3ea38c363b9f0cee9f1c1c2dae4037b047e98328) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Six designs now say what their package offers, how a consumer extends it, and what it
  deliberately does not do — derived from `package.json`'s `exports` map and `src/plugin.ts`,
  not from the README.

  `burgee`, `roundel`, `flagstaff`, `caique`, `closeout` and `bellpull` each gain two sections:
  a table with one row per published subpath and the exported names behind it, an extension
  section stating what a plugin may contribute, what is validated, what is refused and what
  happens on a bad one — and a record of every claim the design was making that the code does
  not support. Each table carries the two commands that re-derive it, so the next reader checks
  rather than trusts.

  The findings are the point. `roundel/import` (`fromBase16`, `fromITerm`) is described in
  `roundel`'s R11 and in its shipped README and exists in neither the `exports` map nor `src/`.
  `bellpull`'s R7 promises a root default export matching `execa`'s and a `./run-path` subpath;
  neither exists, so the `npm-run-path` override recipe cannot be written, and R3's `which` is
  spelled `whichSync` in the code while R5's `toJSON` is `toJson`. `closeout`'s R6 promises a
  root default matching `signal-exit`'s, and the root has no default export.
  `flagstaff`'s R6 names `flagstaff/table` as the `cli-table3` façade — `./table` is the
  built-in grid component and `./cli-table3` is the façade, so a reader following R6 imports the
  wrong module — and its R10 "depends on `roundel` only" is contradicted by the package's own
  shape test, which asserts three dependencies.

  Two structural findings cross package lines. **burgee's `definePlugin` is not the shape the
  layers register against.** `manifest.ts` declares `{ name, commands?, hooks?, enforce? }` —
  no `contract`, no layer key — validates nothing (its body is `return plugin;`), refuses
  nothing, and has no `src/plugin.ts`, so it is outside the vocabulary lock that polices every
  other host. Plugin-contributed commands bypass `defineCommand`, so the reserved-name guard
  and `checkDefinition` never run on them, and a plugin option named `json` silently overwrites
  the envelope flag. **And the shared `schema.json` describes none of the three newest keys:**
  `widgets`, `handlers` and `resolvers` validate only because the root sets
  `additionalProperties: true`, so `caique`, `closeout` and `bellpull` each publish a schema
  that says nothing about the one key they host — and announces itself as flagstaff's file.

  Documentation only: no `packages/**` file is touched, and `npx tsx scripts/plan-progress.ts`
  prints the same 22/36 before and after, byte for byte.

- [#332](https://github.com/ofri-peretz/burgee/pull/332) [`3ea38c3`](https://github.com/ofri-peretz/burgee/commit/3ea38c363b9f0cee9f1c1c2dae4037b047e98328) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - The cliui backtracking guard is checked by shape rather than by clock, after three timing
  instruments failed on it, each differently.

  1. `< 400 ms` at a small size — a CI box returned 440. A 10% margin measures the runner.
  2. A growth **ratio** read **15.04 on macOS CI against 4.09 locally for identical code**,
     batched 256 times, so not noise. Per call that runner was 3x slower at n and 11x slower at
     4n: a 48,000-character cell is 96 KB of UTF-16 where a 12,000-character one is 24 KB, and the
     larger crosses a cache boundary the smaller does not. The ratio measured the memory
     hierarchy, and no ceiling repairs that.
  3. An absolute budget cannot work either, and the numbers say why: at n = 50,000 the quadratic
     implementation costs **1,072 ms here** while the linear one costs **~1,780 ms on CI**.
     Correct code on the slow machine is dearer than buggy code on the fast one, so no threshold
     separates them — and any threshold that passes CI cannot fail locally.

  The bug is one shape: a quantifier with no anchor before it, matched against the row text, so
  the engine retries at every position in a long run and each attempt walks to the end.
  `cliui.ts`'s own comment records the cost — 1,049 ms of `toString()`'s 1,223 ms for a cell of
  50,000 spaces, quadrupling when the cell doubled. The check now asserts that shape is absent:
  deterministic, microseconds, no flake. Reintroducing `str.replace(/ +$/, "")` turns it red.

  What it gives up is generality — it catches the shape rather than the behaviour, so a new
  quadratic written another way would pass. That is stated in the test. Its first run also
  matched the comment that documents the bug, which is why comments are stripped first: the third
  checker in this repository to be caught reading printed source rather than shape.

- [#324](https://github.com/ofri-peretz/burgee/pull/324) [`4a7b4ca`](https://github.com/ofri-peretz/burgee/commit/4a7b4ca59981ec00728fa17c49c3da9618f37868) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `scripts/lanes.ts --check` now grants every lane its own changeset, which `.sdlc/LANES.md` has
  granted since the first run of these lanes.

  The document said it; the script did not implement it. So `--check` called each lane's own
  changeset a stray, and every lane brief had to tell its agent to ignore the result of its own
  boundary check — which makes the check worth nothing. A rule stated in the document and absent
  from the enforcement is the exact drift this file exists to prevent, committed by the file that
  prevents it.

  The exemption is read from the paragraph that grants it rather than written down a second time,
  and it is narrow on both axes: `.changeset/config.json` is still a stray, `*` does not cross a
  slash, and another lane's source file is still another lane's. `lane-boundaries-lock.test.ts`
  holds all three, and goes red when the exemption is reverted.

- [#332](https://github.com/ofri-peretz/burgee/pull/332) [`3ea38c3`](https://github.com/ofri-peretz/burgee/commit/3ea38c363b9f0cee9f1c1c2dae4037b047e98328) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - A lock for PRINCIPLES rule 14: no package does a job another package in the family exists to
  do.

  The family splits nine ways precisely so a program can adopt one layer without the other
  eight. The moment `burgee` measures a string's width itself, or reaches for `chalk` instead of
  `roundel`, that split stops being real and the layers become a directory layout. Until now
  that was intent — every other invariant here has a lock and this one did not.

  The concern table is not restated. `compat-oracle/src/demand.ts` already declares which
  incumbents each layer replaces, and that list _is_ the definition of each layer's job, so the
  rule is derived from it: a package may not depend on an incumbent another layer replaces, nor
  on the one it replaces itself. Needing that job is the same thing as needing the sibling.

  It does not forbid a drop-in façade reproducing its own incumbent — `burgee/commander` spawns
  child processes and forwards five signals because commander's `executableSubcommand` does, and
  commander's own 1360-case suite grades exactly that. Reproducing the incumbent is the
  compatibility claim.

  Family state today: no package depends on any incumbent, its own or a sibling's, and no
  package carries a runtime dependency outside the family.

- [#326](https://github.com/ofri-peretz/burgee/pull/326) [`88f7ba6`](https://github.com/ofri-peretz/burgee/commit/88f7ba65e3a79ed20bf7c5bc4feae8b87684122b) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Read the process through one live seam, and fix the cliui growth gate's instrument.

  `src/runtime.ts` is now the only file in the package that names `process` (PLAN 4.3, Y9); the
  allow-list in `process-reference-lock.test.ts` is down from nine burgee entries to one. Every
  member of the new `host` export is a getter, because the commander and yargs front-ends
  reproduce their incumbents' process contracts and those suites swap `process.argv`, `exit` and
  `env` per test — a captured object literal would hand a test the value from before its own
  swap. Graded before and after: commander 1360/1360, yargs 804/804, unchanged. Two reads that
  had been captured at import are now live, `yargs-parser`'s default env among them.

  `growth()` in `yargs/cliui.test.ts` was measuring the clock on one of its two assertions: at
  n = 12,000 both the cost at n and the cost at 4n fell under the helper's 0.05 ms floor, so the
  padding gate computed `0.05 / 0.05` and reported 1.0000 in 17 of 20 runs. It now calibrates a
  batch until the window at n is a real measurement, and takes the minimum of each side across
  samples rather than the minimum of the per-sample ratios — the second is what let a
  GC-perturbed numerator produce the 10.145 that failed CI. The ceiling stays at 8.

- [#339](https://github.com/ofri-peretz/burgee/pull/339) [`f295630`](https://github.com/ofri-peretz/burgee/commit/f2956301d5f9dcbcac0b001b00ebaf0315891fac) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `schema.json` constrains token names, because it was promising something no host honours.

  `tokens` was described as any name to a `#rrggbb` colour. `roundel`'s `validate()` accepts
  ten semantic names — `error`, `warn`, `ok`, `hint`, `muted`, `command`, `flag`, `value`,
  `heading`, `ground` — and throws on everything else. So a plugin author doing exactly what
  their own `E_PLUGIN_SCHEMA` error tells them, comparing their object against
  `roundel/schema.json`, got a green from the schema and `"accent" is not a token` from
  `register()`. Measured 2026-09-16 with `{ accent: '#336699' }`.

  The schema now carries `propertyNames.enum`, and `scripts/plugin-contract-lock.test.ts`
  pins the enum and the runtime set to each other from both sides, so neither can grow a
  name the other does not know.

  Every host ships a byte-identical copy of this file (`plugin-schema-lock.test.ts` asserts
  it), which is why nine packages are listed. Only the key `roundel` owns is constrained:
  describing `widgets`, `handlers`, `sources`, `resolvers` or `commands` in a file all eight
  hosts share is what made _flagstaff_ start validating caique's key last time
  (`PluginError: plugin.widgets.later: expected object, got boolean`), and those stay in
  `plugin-schema-lock`'s `UNDESCRIBED` list with that reason.

  `linegauge` is in the list for a different change: `ceilings.json`'s R9 block now records
  the bar as D1's tree-inclusive ceiling — 83,538 against 170,342, a ratio of 0.4904 — and
  keeps the superseded `get-east-asian-width` bar beside it with the count of entries that
  cleared it.

- [#326](https://github.com/ofri-peretz/burgee/pull/326) [`88f7ba6`](https://github.com/ofri-peretz/burgee/commit/88f7ba65e3a79ed20bf7c5bc4feae8b87684122b) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - The process-reference lock now catches the **binding**, not only the member read.

  The seams built for PLAN 4.3 showed the hole up. `flagstaff/src/runtime.ts` reads the world
  through `import process from 'node:process'`, and `roundel/src/runtime.ts` through a guarded
  `(globalThis as { process?: … }).process` bound to a local — and both files passed the existing
  pattern **untouched**. Their being on the allow-list was a statement of intent rather than
  something the lock enforced.

  Which means any file in any package could have done the same and stayed green: bind the global
  once, then read `proc.env` forever, because the member read is now on a local whose name a
  textual pattern cannot tell from any other. The same hole the `globalThis.` lookbehind closed
  in September, reopened through a different door.

  Proven against a real file in `linegauge/src` — a package with no allow-list entry — in both
  spellings, each green before the change and caught after. And the new pattern's own first catch
  was a **comment** in `chalk.ts` saying where a cast had moved to, which is the defect this file
  already carries a paragraph about: a checker that reads printed source and not shape. Comments
  are stripped before it sees them, and that case is now one of its row-by-row tests.

- [#321](https://github.com/ofri-peretz/burgee/pull/321) [`48aec0a`](https://github.com/ofri-peretz/burgee/commit/48aec0a500b474be8f4c477f1d18433e4b3467bf) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Every package README now carries a generated `## Where it sits`: which key plugins register
  under, and what is above and below the package in the family (PLAN 5.2).

  Both facts are derived rather than written down a second time. The keys come off each
  package's own `export interface Plugin` — its members besides `name` and `contract` _are_ the
  keys — and the edges come from the manifests' own dependency lists. The first version matched
  a fixed alternation of key names instead and reported flagstaff as hosting none, when it hosts
  four the alternation had never heard of: the whole argument against a second copy, made by the
  function that was the second copy.

  `scripts/readme-lock.test.ts` holds it. The assertion that matters is 5.2's own
  done-condition — a hand edit fails — and it is proven rather than asserted: the test edits a
  README and requires the check to notice. Tampering `caique`'s real file with a `gadgets` key
  turns it red, which is the check that makes the other five mean something.

- Updated dependencies [[`3ea38c3`](https://github.com/ofri-peretz/burgee/commit/3ea38c363b9f0cee9f1c1c2dae4037b047e98328), [`3ea38c3`](https://github.com/ofri-peretz/burgee/commit/3ea38c363b9f0cee9f1c1c2dae4037b047e98328), [`3ea38c3`](https://github.com/ofri-peretz/burgee/commit/3ea38c363b9f0cee9f1c1c2dae4037b047e98328), [`c8acb28`](https://github.com/ofri-peretz/burgee/commit/c8acb2848714a1cbe3e26a2f9895d7498fb4f096), [`fc640dd`](https://github.com/ofri-peretz/burgee/commit/fc640ddec11255c12d1e0948c5b8e99cc3f3263b), [`3f92a60`](https://github.com/ofri-peretz/burgee/commit/3f92a6099b1b8d5d476c64405ca963d40bf9af45), [`3ea38c3`](https://github.com/ofri-peretz/burgee/commit/3ea38c363b9f0cee9f1c1c2dae4037b047e98328), [`fc640dd`](https://github.com/ofri-peretz/burgee/commit/fc640ddec11255c12d1e0948c5b8e99cc3f3263b), [`3ea38c3`](https://github.com/ofri-peretz/burgee/commit/3ea38c363b9f0cee9f1c1c2dae4037b047e98328), [`c8acb28`](https://github.com/ofri-peretz/burgee/commit/c8acb2848714a1cbe3e26a2f9895d7498fb4f096), [`c8acb28`](https://github.com/ofri-peretz/burgee/commit/c8acb2848714a1cbe3e26a2f9895d7498fb4f096), [`88f7ba6`](https://github.com/ofri-peretz/burgee/commit/88f7ba65e3a79ed20bf7c5bc4feae8b87684122b), [`3f92a60`](https://github.com/ofri-peretz/burgee/commit/3f92a6099b1b8d5d476c64405ca963d40bf9af45), [`f295630`](https://github.com/ofri-peretz/burgee/commit/f2956301d5f9dcbcac0b001b00ebaf0315891fac), [`c8acb28`](https://github.com/ofri-peretz/burgee/commit/c8acb2848714a1cbe3e26a2f9895d7498fb4f096), [`3f92a60`](https://github.com/ofri-peretz/burgee/commit/3f92a6099b1b8d5d476c64405ca963d40bf9af45)]:
  - bellpull@0.1.0
  - closeout@0.2.0
  - linegauge@0.3.0
  - seniority@0.2.0
  - roundel@0.3.1

## 0.6.1

### Patch Changes

- [#280](https://github.com/ofri-peretz/burgee/pull/280) [`50cc1a3`](https://github.com/ofri-peretz/burgee/commit/50cc1a325bc99b144b4e1dba701de624bbd76de6) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - The B1 agent-cost axis now recognises an empty credential as no credential. A workflow that maps an unset repository secret into the environment leaves the variable **present and empty**, not absent, so a guard testing against `undefined` never fired: the axis ran, `claude` failed to authenticate on all 25 task-runs, and the skip reported that `claude` "answered but nothing it produced passed a task's own check" — pointing a reader at a prompt-quality problem that did not exist.

- [#278](https://github.com/ofri-peretz/burgee/pull/278) [`862e837`](https://github.com/ofri-peretz/burgee/commit/862e83716b66e9aa363a0fa3b703cc9cd38b8929) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - **🐛 Fix** — help screens wrap against the real width: `width`, `strip` and `wrap` come from `linegauge`

  `burgee/yargs`' cliui port carried its own `stringWidth`, `stripAnsi` and a wrap-ansi
  implementation. The strip was wrong: the ITU T.416 sub-parameter form
  `ESC[38:2::255:0:0m` — what chalk emits for truecolor — left `:2::255:0:0m` in the string,
  so a 13-column string measured as 25 and every help screen wrapped against a width that was
  not the width. linegauge owns measuring and wrapping text and had already fixed it.

## 0.6.0

### Minor Changes

- [#265](https://github.com/ofri-peretz/burgee/pull/265) [`0750ebc`](https://github.com/ofri-peretz/burgee/commit/0750ebcf2a66c0254a8f9ae52c83d3d50a37b67a) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - **♻️ Refactor** — precedence and config discovery come from `seniority` rather than a second copy

  burgee carried its own `precedence.ts` and `config.ts`; `config.ts` was byte-identical to
  seniority's and `precedence.ts` differed by nineteen lines. Two copies of a precedence order
  is two answers to "where did this value come from", and `--explain` is only worth anything
  if the thing that picked the value is the thing that reports it.

  The public surface is unchanged — `resolve`, `explain`, `envName`, `screaming`,
  `ConfigError` and their types are still exported from `burgee`, now re-exported from
  `seniority@^0.1.0`, which is a new runtime dependency.

## 0.5.0

### Minor Changes

- [#194](https://github.com/ofri-peretz/burgee/pull/194) [`8693415`](https://github.com/ofri-peretz/burgee/commit/86934153a9389d7e2380c07424cd414748e696a1) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - burgee consumes `roundel` instead of carrying a copy of it.

  `contrast.ts` existed twice — the same WCAG luminance and ratio code in both packages,
  identical constants and identical maths, differing only in which package name the hex error
  message says. That is what a rule forbidding the dependency arrow produces: it does not
  remove the need, it converts it into a copy, which is the one outcome zero-external-deps
  exists to prevent.

  The family order now runs bottom-up — foundation, output stack, engine — so each layer
  consumes the layers below it. burgee is last, because a command declares itself and then
  asks the layers beneath it to render, colour and prompt.

  What a caller installs still comes from one repo: **zero external dependencies** is
  unchanged, and is the claim that was ever worth making.

- [#246](https://github.com/ofri-peretz/burgee/pull/246) [`14b4cb2`](https://github.com/ofri-peretz/burgee/commit/14b4cb2be80deb78079aea2d748ad44aac9a96ff) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `--schema` publishes `relations` (S2/S6). `validate.ts` has enforced `exactlyOneOf`,
  `conflicts`, `implies` and the rest since the surface shipped, and the schema never said so —
  an agent could only discover a constraint by violating it. A predicate `implies` publishes as
  `"(predicate)"` rather than the `null` `JSON.stringify` would leave.

### Patch Changes

- Updated dependencies [[`214f6f8`](https://github.com/ofri-peretz/burgee/commit/214f6f83b16068d7dc53d79799fba03c26a3cbe2), [`214f6f8`](https://github.com/ofri-peretz/burgee/commit/214f6f83b16068d7dc53d79799fba03c26a3cbe2)]:
  - roundel@0.3.0

## 0.4.0

### Minor Changes

- [#156](https://github.com/ofri-peretz/burgee/pull/156) [`799a461`](https://github.com/ofri-peretz/burgee/commit/799a4616881f6cedc0bb1eae31b0b186969b217c) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `--schema` is compact by default (agent-headroom R1). The document an agent reads to
  discover a CLI drops 42% — 39,512 → 22,964 bytes on the large reference demo — for a
  byte-identical parse. `--format=json-pretty` restores indentation for a person reading it.
  Both writers change: the engine's `--schema` and the commander front-end's.

- [#160](https://github.com/ofri-peretz/burgee/pull/160) [`b6fc349`](https://github.com/ofri-peretz/burgee/commit/b6fc349b113f50b6aba3961718aaea76c0f84ffa) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Every boolean option accepts `--no-<name>`. burgee's precedence is `flag > env > config file > package.json field > default`, and the config and package.json layers set options by name — so any boolean can arrive `true` without the user typing anything, while a boolean flag carries no value and `--x=false` is refused. Before this the top layer of that chain could only ever say `true`, and a boolean turned on in a config file could not be turned off from the command line at all. `--x` and `--no-x` together: the later one wins. String options are unaffected, and `--no-config` still means "load none".

- [#134](https://github.com/ofri-peretz/burgee/pull/134) [`7a38fe7`](https://github.com/ofri-peretz/burgee/commit/7a38fe7c321ca2efe54d89a73dcba9205316dc2d) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee/brand` gains three options, so a family of marks can come out of one declaration.

  `shape` replaces the swallowtail with your own silhouette (SVG path data, same `0 0 100 100` box, filled `evenodd` so a nested subpath cuts a hole) — for a sibling brand whose name is not a flag: a roundel is rings, a parrot is a parrot.

  `sheen` lays a soft highlight across the field, clipped to the silhouette and drawn under the charge, so the mark keeps the contrast it was measured at. `alive()` is the same mark with that highlight sweeping across — for a site header, never a favicon — parked still under `prefers-reduced-motion`.

  `bevel` is the third dimension a logo can afford: two stroked copies of the silhouette clipped to itself, light offset toward the light source and dark away from it, so the edge lifts and the face stays flat. Sub-pixel at 16px, where it disappears rather than muddies.

  All three are additive: a brand that declares none renders byte-for-byte what it rendered before.

- [#151](https://github.com/ofri-peretz/burgee/pull/151) [`8f1043a`](https://github.com/ofri-peretz/burgee/commit/8f1043ae367aeb4b7d107e18491bb6c2653cde42) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - A mistyped option now says which one was meant: `error: unknown option --nmae` / `hint: did you mean --name?`, taken from the options the command declared. Exit 2 already told an agent to rewrite the command; this is the half that says how. Previously the native path printed `node:util.parseArgs`'s own message — three lines about `--` and positional arguments, which never mentions the option the caller almost typed — while the commander façade had suggestions all along.

  The edit-distance code is loaded on the failure path only, so `import { defineCommand } from 'burgee'` does not carry it. The core entry point got _smaller_, because the single-dash hint moved out of it too.

### Patch Changes

- [#151](https://github.com/ofri-peretz/burgee/pull/151) [`8f1043a`](https://github.com/ofri-peretz/burgee/commit/8f1043ae367aeb4b7d107e18491bb6c2653cde42) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - The repo now dogfoods a twelfth Interlace ESLint plugin, `browser-security`, scoped to the docs app — 41 more rules at `error` over the surface the engine never touches and a browser application does.

- [#151](https://github.com/ofri-peretz/burgee/pull/151) [`8f1043a`](https://github.com/ofri-peretz/burgee/commit/8f1043ae367aeb4b7d107e18491bb6c2653cde42) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Marks for the foundation tier — `linegauge`, `seniority`, `bellpull` and `closeout` — from the same declaration as the other four. No API change: `burgee/brand` already had `shape`, and this is four more of them.

- [#162](https://github.com/ofri-peretz/burgee/pull/162) [`a447fc4`](https://github.com/ofri-peretz/burgee/commit/a447fc434b2162a61b6cf5ce7814cacb1559d06a) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Completions offer `--no-<name>` for every declared boolean, in all four shells, and fish emits the CLI form rather than the declaration name. fish alone built its own spelling instead of going through `flags()`, so it had been completing `-l dryRun` where the flag is `--dry-run` — a flag the parser refuses — for every camelCase option. The reserved surfaces are excluded: `--no-json` and `--no-help` are not accepted by the parser and are not offered.

- [#158](https://github.com/ofri-peretz/burgee/pull/158) [`97ca535`](https://github.com/ofri-peretz/burgee/commit/97ca53593c253d2504892cda62247a0d574bd698) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `--version` and `-V` answer on a program that is a pure command group. `dispatch` had always handled them, but only once a command resolved, so a program whose root runs nothing fell through to `unknown command "--version"` and exit 2 — which under E1 means _rewrite the command_. Real commander and real yargs both print the version and exit 0 for the identical program.

- [#170](https://github.com/ofri-peretz/burgee/pull/170) [`3e4071c`](https://github.com/ofri-peretz/burgee/commit/3e4071c75e417c71961891e18a85238deb3e3d8d) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee/yargs` finds its locale table from the package root rather than from the depth of
  one file. It resolved `../locales` relative to itself, which was correct only while that file
  sat directly in `dist/`; the moment it moved into a directory the path became `dist/locales`,
  y18n returned the key for every string, and 14 of yargs' own 804 tests failed. Walking up to
  `package.json` resolves the same from `src/`, from `dist/`, and from an installed
  `node_modules/burgee/dist/`.

## 0.3.0

### Minor Changes

- [#24](https://github.com/ofri-peretz/burgee/pull/24) [`cf951de`](https://github.com/ofri-peretz/burgee/commit/cf951de876b23c5f9bc38d734e3028b723983178) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `Runtime` gains a `clock` (`now`, `schedule`) with a deterministic fake in `burgee/testing`, and `renderHelp` accepts `{ color, theme }` — a structural token map the output stack can fill without burgee importing it.

- [#33](https://github.com/ofri-peretz/burgee/pull/33) [`8ad4d4a`](https://github.com/ofri-peretz/burgee/commit/8ad4d4abb5077433dfa875f3f1a95480e95c2a52) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - Large CLIs (M1–M6): `load: () => import('./x.js')` on a command loads its handler on dispatch only — help, `--schema` (which marks it `lazy`), completions and the MCP tool list are complete without it; `sharedOptions(name, specs)` declares a set once and each copy is tagged `sharedFrom` in the schema; a command with `deprecated: 'new'` warns once on stderr and runs; `group` and `plugin` ride on the schema; `resolveCommand` and `runCommand` are public. The commander façade gains `.deprecate(use?)` and projects `.helpGroup()`. A required positional that argv did not supply is now a usage error naming it — it had never been enforced.

- [#23](https://github.com/ofri-peretz/burgee/pull/23) [`0770990`](https://github.com/ofri-peretz/burgee/commit/07709908c423411ab97252812dfa5ec8d3cf4e0a) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee dev <entry>`: your agent is connected to your CLI while you write it. The entry (exporting `program` as a burgee manifest, a commander `Command` or a yargs instance) is served as MCP on stdio; on every save it is re-imported as a fresh module graph, the served manifest is swapped, `notifications/tools/list_changed` goes out, and the diff plus the rendered help are printed on stderr. Dev-time only and removable: nothing a shipped CLI imports can reach it. `startMcp()` is the swappable server `serveMcp()` now wraps.

- [#19](https://github.com/ofri-peretz/burgee/pull/19) [`9670224`](https://github.com/ofri-peretz/burgee/commit/96702248dfccff5074874ce4a3d0b9d19754a3fc) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - burgee's additions on yargs syntax, guarded so a program that asks for none of them runs exactly as on yargs (804 / 804 still): `yargs.manifest` projected from what the program registered (builders run on a scratch instance, as yargs' completion does), `use(plugin)` with `preRun`/`postRun` around every handler, `.effects()` inside a builder, `--json` as the `{ ok, data, meta }` envelope when the program did not declare it anywhere in its tree, `--schema`, `--mcp` and `completion <shell>` from the manifest, and `.burgee({ stdout, stderr, exit })` injecting the streams and reporting E1 exit codes.

- [#16](https://github.com/ofri-peretz/burgee/pull/16) [`c7d1aa0`](https://github.com/ofri-peretz/burgee/commit/c7d1aa0f271c0733b42213c0351e6aebcc7dd909) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee/yargs/parser`: the ported yargs-parser as its own entry — what `import parser from 'yargs-parser'` gave, for a program that imported the parser directly. With it, and with the compatibility harness able to `require()` its vendored root as a package, both façades now pass **100%** of their hosts' own suites: `burgee/commander` 1,361 / 1,361 and `burgee/yargs` 804 / 804.

## 0.2.0

### Minor Changes

- [#14](https://github.com/ofri-peretz/burgee/pull/14) [`95a954f`](https://github.com/ofri-peretz/burgee/commit/95a954f82f44ce1249fa1a051e529ad46b258376) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee/yargs` and `burgee/yargs/helpers`: yargs 18 ported method for method — with its whole dependency tree (yargs-parser 22, cliui 9 with string-width and wrap-ansi, y18n 5 and the 29 locales, escalade, get-caller-file) reimplemented over no dependency — and graded by yargs' own suite: **782 / 804** on the first run, one short of the 783 the real package scores in the same environment. The one test left asserts that `Parser` is the same object as the `yargs-parser` npm package, which a dependency-free port cannot be. `import yargs from 'burgee/yargs'` and `import { hideBin, applyExtends, Parser } from 'burgee/yargs/helpers'` are the drop-in; `examples/conformance` proves the demo byte-identical on both.

### Patch Changes

- [#13](https://github.com/ofri-peretz/burgee/pull/13) [`21d0f4f`](https://github.com/ofri-peretz/burgee/commit/21d0f4f32722b19831fcfa3c7f4d73849eaeaed5) Thanks [@ofri-peretz](https://github.com/ofri-peretz)! - `burgee/commander`: `parse()` is synchronous again and `parseAsync()` starts synchronously, exactly as commander's do. Since the `--schema`/`--mcp` surface landed, both went through an `async` surface check, so a synchronous action ran a microtask after `parse()` returned and a `preAction` hook after `parseAsync()` handed back its promise — commander's own suite asserts on both after every parse. 638 of its 1,331 tests had been failing on `main` while the Compatibility job reported success, because a `| tee` pipe hid the grader's exit code; every workflow step that pipes into `tee` now runs with `pipefail`.

---

# Coming from blessed

> Move a blessed program to controlroom, the burgee family's blessed alternative: screen, box, list, key handling and the render loop mapped onto open(), layout trees, keymaps and flagstaff panes, what does not map, and what burgee migrate reports for a blessed program.

Source: https://burgee.interlace.tools/docs/coming-from/blessed

**controlroom** is the burgee family's **blessed alternative** for keyboard-driven terminal
programs, inline or full-screen. `open()`, layout, tabs and keymaps, the input line and
plugins all ship, since 0.2.0. A screen it opens works for a person at a terminal, and
prints a static projection of every pane for a pipe, CI, a screen reader or an agent.

Only drawing inline output, with no keys? You want flagstaff:
[Which one do I need?](/docs/packages#which-one-do-i-need)

## Migrate from blessed: not one import

There is no `controlroom/blessed`, and none is planned. blessed's surface is too large to
reproduce honestly, so moving is a rewrite of each screen, not of the import line.
`burgee migrate` finds the blessed sites in your project and names the section of this page
that covers each one:

```bash
npx burgee migrate --dry-run --json
```

It reports and never rewrites: a blessed screen and a controlroom screen are different
shapes, so each one is a decision, not a substitution. For this program:

```js
const blessed = require('blessed');

const screen = blessed.screen({ smartCSR: true });
const list = blessed.list({ items: ['build', 'test'], keys: true });
screen.append(list);
screen.key(['q', 'C-c'], () => process.exit(0));
screen.render();
```

the report's `guided` list reads, one entry per site:

```json
[
  { "file": "src/ui.js", "line": 1, "from": "blessed", "pattern": "import", "guide": "https://burgee.interlace.tools/docs/coming-from/blessed#the-mapping" },
  { "file": "src/ui.js", "line": 3, "from": "blessed", "pattern": "screen", "guide": "https://burgee.interlace.tools/docs/coming-from/blessed#screen" },
  { "file": "src/ui.js", "line": 4, "from": "blessed", "pattern": "list", "guide": "https://burgee.interlace.tools/docs/coming-from/blessed#list" },
  { "file": "src/ui.js", "line": 6, "from": "blessed", "pattern": "key", "guide": "https://burgee.interlace.tools/docs/coming-from/blessed#key-handling" },
  { "file": "src/ui.js", "line": 7, "from": "blessed", "pattern": "render", "guide": "https://burgee.interlace.tools/docs/coming-from/blessed#render-loop" }
]
```

A site is reported only when the receiver came from blessed in the same file:
`screen.key(` on a `screen` from `blessed.screen()` is a key binding, and `screen.key(` on
anything else is not. A screen passed in from another file is not followed, but that file's
own `require('blessed')` still is. The exit code stays 0, because nothing was refused. The
[Migrate](/docs/migrate) page has the whole report.

## The same screen on controlroom

A list of steps with a log under it, a key to rerun and a key to quit:

```js title="ui.mjs"
import { open, processRuntime } from 'controlroom';
import { logTail } from 'flagstaff/log-tail';
import { tasks } from 'flagstaff/tasks';

const steps = (build, test) => ({ tasks: [{ title: 'build', status: build }, { title: 'test', status: test }] });

const screen = open(processRuntime(), {
  screen: 'alternate',
  json: process.argv.includes('--json'),
  layout: {
    direction: 'column',
    parts: [{ size: 'fit', content: 'steps' }, { content: 'log' }],
  },
  keymap: { r: 'rerun', q: 'quit', 'ctrl+c': 'quit' },
  panes: {
    steps: { component: tasks(), state: steps('running', 'pending'), label: 'Steps' },
    log: { component: logTail(), state: { lines: [] }, label: 'Log' },
  },
  onAction(action, s) {
    if (action === 'rerun') s.update('steps', steps('running', 'pending'));
  },
});

screen.update('log', { lines: ['tsc -p .'] });
screen.update('steps', steps('ok', 'running'));
screen.update('steps', steps('ok', 'ok'));
screen.close();
```

On a terminal this takes the alternate screen and repaints as the steps move. Piped, it
prints each pane under its label, and each settled line once, with no escape byte:

```text title="node ui.mjs | cat"
Steps

Log

┊ tsc -p .
✔ build
✔ test
```

`node ui.mjs --json` writes one NDJSON event per change to stderr, named after its pane
(`{"event":"steps","state":{…}}`), and leaves stdout for the program's result.

## The mapping

| blessed | controlroom |
| :-- | :-- |
| `blessed.screen()` | `open(runtime, { screen: 'alternate' })` |
| `screen.destroy()` | `close()` on what `open()` returned |
| `blessed.box({ top, left, width, height })` | a pane in a layout tree, holding a flagstaff component |
| `blessed.list()` | flagstaff's `tasks` in a pane, for a list you show |
| `blessed.listbar()` | a pane over flagstaff's `tabBar`, with the screen's tab state |
| `blessed.log()` | flagstaff's `logTail` in a pane |
| `screen.key([...], fn)` | an entry in a keymap, which is data, and `onAction` |
| `screen.on('keypress', fn)` | the same keymap |
| `screen.render()` | nothing: an `update()` repaints |
| `screen.program.alternateBuffer()` | `screen: 'alternate'`, left on every exit path |
| `blessed.textbox()` | the input line: caique's line editor in a pane |
| `mouse: true`, `on('click')` | nothing |
| `blessed.textarea()`, `form` | nothing: a question asked once is caique's prompt |

### Screen

`blessed.screen()` takes over the terminal when it is constructed. controlroom's
`open(runtime, { screen: 'alternate' })` does the same **only** when roundel's output policy
says `tty` and stdin can go raw. In every other mode it opens a static screen instead, so the
same program runs in a pipe, in CI and under `--json`. `runtime` is the structural runtime the
family's packages take instead of reading `process`; `processRuntime()` is the real one.

`screen: 'inline'`, the default, is a mode blessed does not have: a live region drawn under
the program's own output, with `commit(text)` releasing text above it into the terminal's
scrollback. It is ink's shape, and a chat CLI's.

`screen.destroy()` becomes `close()`, which hands the terminal back and does nothing the
second time.

`burgee migrate` reports `blessed.screen()`, `new blessed.Screen()` and `blessed.program()`
here. A program is blessed's lower-level handle on the terminal, and what it does for a
blessed screen is what `open()` does for a controlroom one.

### Box

A blessed box positions itself: `top`, `left`, `width` and `height` as cells, percentages or
`'center'`. In controlroom a pane does not position itself. One layout tree splits the screen
into rows and columns of fixed, fractional (`{ fr, min }`) and fit-to-content sizes, and a
pane is a name in that tree. `layout()` is the arithmetic `open()` runs on every paint, and
you can call it yourself:

```js
import { layout } from 'controlroom';

const tree = {
  direction: 'column',
  parts: [
    { content: { direction: 'row', parts: [{ size: { fr: 1, min: 20 }, content: 'learn' }, { size: { fr: 2 }, content: 'tasks' }] } },
    { size: 8, content: 'logs' },
  ],
};
layout(tree, { x: 0, y: 0, width: 100, height: 30 }).get('tasks');
// { x: 34, y: 0, width: 66, height: 22 }
```

There is no flexbox and no constraint solver: one pass hands out the fixed cells and the
minimums, and a second shares the rest by fraction. A terminal too small for the minimums
clips the later parts, never the first.

What a pane draws is any flagstaff component, given as `{ component, state, label }` under
`panes`. A border, padding and a title come from flagstaff's `boxComponent`.

`burgee migrate` reports `box()`, `text()`, `element()`, `log()` and `layout()` here. The
last is blessed's own auto-positioning container, which the layout tree replaces outright.

### List

A list you **show**, such as steps with a state each, is flagstaff's `tasks` in a pane.
Outside a terminal it prints one line per task that has settled. A list the user **picks
from**, blessed's `keys: true` with a `select` event, has no pane component. A pick is a
prompt, and prompts are caique's: `select`, asked before or after the screen, not inside it.

`listbar()` maps to a tab bar: a pane over flagstaff's `tabBar`, kept in step with the
screen's active tab from `onAction`. Mark it `liveOnly: true`, because off a terminal there
are no tabs to switch and every pane prints.

`burgee migrate` reports `list()`, `listtable()` and `listbar()` here.

### Key handling

blessed binds a key to a function: `screen.key(['q', 'C-c'], fn)`. controlroom binds a key
to an **action name**, in a keymap that is plain data. The screen's tabs, focus and collapsed
panes move through a reducer, and your `onAction(action, screen)` sees every action after
it. The hint line is generated from the same keymap, so it cannot advertise a key that is
not bound.

```js
import { hints, initial, reduce } from 'controlroom';

const keymap = { left: 'tab.prev', right: 'tab.next', s: 'toggle:status', q: 'quit', 'ctrl+c': 'quit' };
const labels = { 'tab.prev': 'switch tab', 'tab.next': 'switch tab', 'toggle:status': 'toggle status', quit: 'quit' };

let state = initial(['Status', 'Tail logs'], ['learn', 'tasks']);
state = reduce(state, keymap.right); // state.active is 1: the second tab
hints(keymap, labels); // '←→ switch tab  s toggle status  q/^C quit'
```

An action the reducer does not know, such as `quit` here, leaves the state alone and is the
program's own to handle; a live screen closes on `quit`. Key names are spelled as caique's
key decoder spells them:

| blessed | controlroom |
| :-- | :-- |
| `C-c` | `ctrl+c` |
| `M-x` | `meta+x` |
| `S-tab` | `shift+tab` |
| `escape`, `left`, `right`, `q` | unchanged |

Raw mode is taken once for the screen's whole life and handed back on every exit. Keys are
read only when stdout is a terminal and stdin can go raw. Everywhere else,
`screen.dispatch(action)` runs an action as if its key had been pressed, so nothing waits
for a key nobody can press.

`burgee migrate` reports `key()`, `onceKey()`, `unkey()` and `removeKey()` here, on a
screen, an element or a program, and every `on()` or `once()` whose event name starts with
`key`: `keypress`, and blessed's `key q` form.

### Render loop

blessed draws nothing until you call `screen.render()`, so a blessed program calls it after
every change. controlroom has no render call to make. `update(pane, state)` repaints: the
layout is composed from every pane's frame and handed to flagstaff's frame writer, which
writes only the rows that changed, inside one synchronized-output block, and the screen is
laid out again on resize. controlroom never writes to the terminal itself. When you move a
screen, delete its `render()` calls rather than translating them. `burgee migrate` reports
each one, including `box.screen.render()`.

### Alternate screen

blessed's screen switches to the alternate buffer itself, through its program's
`alternateBuffer()`, and `normalBuffer()` switches back. controlroom's is the
`screen: 'alternate'` option. The alternate screen, the hidden cursor, raw mode and bracketed
paste are each entered through closeout with their undo registered in the same call, so
`close()`, Ctrl+C, a signal and a throw all hand the terminal back. There is no
`normalBuffer()` to remember.

The alternate screen has no scrollback, so text given to `commit()` there is kept and handed
to the main screen when the screen closes.

`burgee migrate` reports `alternateBuffer()` and `normalBuffer()` here, on a program or on
`screen.program`.

## What does not map

These are out of scope, so a program that depends on them should stay on blessed.

### Mouse

Clicks, the wheel and drags (`mouse: true`, `screen.enableMouse()`, `on('click')`) have no
controlroom equivalent, and none is planned. `burgee migrate` reports each mouse site it can
see, so you know how many there are: `enableMouse()`, and `on()` with `mouse`, `click`,
`mousedown`, `mouseup`, `mousemove`, `mouseover`, `mouseout`, `wheeldown` or `wheelup`.

### Text editing in a pane

`textbox()` maps to the **input line**: caique's line editor hosted in one pane, with
history, completion and pasted text arriving whole. Keys go to it while it has focus and fall
through to the keymap when it does not use them, and in a pipe each line of stdin is one
entry. It is the `input: { editor, pane, onSubmit, onEnd }` option of `open()`.

`textarea()` and `form`, a multi-line editor or several fields inside the layout, do not
map. A question asked once is a prompt, and prompts are caique's. `burgee migrate` reports
`textbox()` and `textarea()` here.

### Legacy Windows consoles

controlroom handles no Windows legacy console quirks beyond what Node's own terminal handling
does. If your blessed program relies on behaviour specific to an old Windows console, check
that before you move it.

The rest of blessed's widget catalogue, including images and embedded terminals, has no
controlroom counterpart either. A pane draws any flagstaff component, and you can register
your own as a plugin.

## Is controlroom compatible with blessed?

**No, by design.** There is no drop-in and nothing is graded: no blessed suite runs against
controlroom, and none will, because the API is not being reproduced. The
[Compatibility](/docs/compatibility) page grades controlroom's drop-in for **ink**,
`controlroom/ink`, by ink 8.0.0's own suite. It has no blessed row.

## What you gain over blessed

- **Every caller gets an answer, not just a terminal.** Off a terminal a screen prints each
  pane's static projection under its label, with no escape byte, no carriage return and no
  cursor movement, and only the lines that changed on each update. Tabs hide nothing, and a
  `liveOnly` pane such as the hint line is not printed.
- **`--json` is an event stream.** One NDJSON event per change on stderr, named after the
  pane, so an agent reads the same program a person watches, with stdout left for the result.
- **It never waits for a key nobody can press.** Behind a pipe, in CI or with `< file`, a
  screen reads no keys, and `dispatch()` is what the program has instead.
- **Inline or full screen.** blessed always takes the whole terminal; controlroom can also
  draw under the program's output and keep a transcript in the scrollback.
- **One render engine.** The spinner in a pane is the same flagstaff component, drawn by the
  same frame loop, as the spinner in an ordinary CLI.
- **Nothing installed from outside the family.** That is a rule every published package in
  this repository is held to by a lock, controlroom included.

This page does not say what blessed writes to a pipe or under CI, and makes no size or speed
comparison against blessed: none has been measured here. controlroom's own bytes, per
export, are on the [weight](/docs/weight) page.

## When to switch from blessed

Switch a screen if its output has to work for a pipe, CI, a screen reader or an agent as well
as for a person at a terminal, or if you want it inline under the program's output. Stay on
blessed if you depend on the mouse, on multi-line editing or forms inside the screen, or on
widgets outside the mapping above. The [package page](https://controlroom.interlace.tools) has the
whole API.

---

# Coming from neo-blessed

> Move a neo-blessed program to controlroom, the burgee family's neo-blessed alternative. neo-blessed keeps blessed's API, so its mapping is blessed's; this page gives it section by section, with what does not map and what burgee migrate reports.

Source: https://burgee.interlace.tools/docs/coming-from/neo-blessed

**controlroom** is the burgee family's **neo-blessed alternative** for keyboard-driven
terminal programs, inline or full-screen. `open()`, layout, tabs and keymaps, the input line
and plugins all ship, since 0.2.0.

neo-blessed is a fork of blessed that keeps blessed's API under another name: the same
`screen()`, `box()`, `list()`, `key()` and `render()`. So its path to controlroom is
blessed's, and the runnable examples live once, on
[Coming from blessed](/docs/coming-from/blessed). This page keeps the same sections so that
every link `burgee migrate` prints for a neo-blessed site lands on one.

Only drawing inline output, with no keys? You want flagstaff:
[Which one do I need?](/docs/packages#which-one-do-i-need)

## Migrate from neo-blessed: not one import

There is no `controlroom/neo-blessed`, for blessed's reason: the surface is too large to
reproduce honestly. `burgee migrate` reports every neo-blessed site it can see, with
`"from": "neo-blessed"` and a link to the section below, and rewrites none of them:

```bash
npx burgee migrate --dry-run --json
```

A site is reported only when its receiver came from neo-blessed in the same file, by
`require('neo-blessed')`, `import blessed from 'neo-blessed'` or a destructured factory. The
exit code stays 0, because nothing was refused.
[blessed's page](/docs/coming-from/blessed#the-same-screen-on-controlroom) has a whole screen
moved, with what it prints in a pipe.

## The mapping

| neo-blessed | controlroom |
| :-- | :-- |
| `blessed.screen()` | `open(runtime, { screen: 'alternate' })` |
| `blessed.box()` | a pane in a layout tree, holding a flagstaff component |
| `blessed.list()` | flagstaff's `tasks` in a pane, for a list you show |
| `screen.key([...], fn)` | an entry in a keymap, which is data, and `onAction` |
| `screen.render()` | nothing: an `update()` repaints |
| `screen.program.alternateBuffer()` | `screen: 'alternate'`, left on every exit path |
| `blessed.textbox()` | the input line: caique's line editor in a pane |
| `mouse: true`, `on('click')` | nothing |
| `blessed.textarea()` | nothing: a question asked once is caique's prompt |

The full table, with `listbar()`, `log()` and `destroy()`, is
[blessed's](/docs/coming-from/blessed#the-mapping).

### Screen

`blessed.screen()`, `new blessed.Screen()` and `blessed.program()` become
`open(runtime, { screen: 'alternate' })`, which takes the terminal only when there is one and
opens a static screen everywhere else. `screen: 'inline'`, the default, draws under the
program's own output instead. See [blessed's Screen section](/docs/coming-from/blessed#screen).

### Box

`box()`, `text()`, `element()`, `log()` and `layout()` become panes: names in one layout
tree of rows and columns with fixed, fractional and fit-to-content sizes, each drawing a
flagstaff component. See [blessed's Box section](/docs/coming-from/blessed#box).

### List

`list()` and `listtable()` you show become flagstaff's `tasks` in a pane. A list the user
picks from has no pane component; a pick is caique's `select` prompt, outside the screen.
`listbar()` becomes a pane over flagstaff's `tabBar`, kept in step with the screen's tab
state. See [blessed's List section](/docs/coming-from/blessed#list).

### Key handling

`key()`, `onceKey()`, `unkey()` and `removeKey()`, and every `on()` or `once()` whose event
starts with `key`, become entries in a keymap that is plain data, `{ q: 'quit' }`. The
screen's tabs, focus and collapsed panes move through a reducer, `onAction` sees every
action, and the hint line is generated from the same keymap. `C-c` is spelled `ctrl+c`. See
[blessed's Key handling section](/docs/coming-from/blessed#key-handling).

### Render loop

Every `render()`, including `box.screen.render()`, is deleted rather than translated: an
`update()` repaints through flagstaff's frame writer. See
[blessed's Render loop section](/docs/coming-from/blessed#render-loop).

### Alternate screen

`alternateBuffer()` and `normalBuffer()`, on a program or on `screen.program`, become the
`screen: 'alternate'` option, left on every exit path through closeout. See
[blessed's Alternate screen section](/docs/coming-from/blessed#alternate-screen).

## What does not map

Out of scope, so a program that depends on these should stay on neo-blessed.

### Mouse

`enableMouse()`, and `on()` with `mouse`, `click`, `mousedown`, `mouseup`, `mousemove`,
`mouseover`, `mouseout`, `wheeldown` or `wheelup`. None is planned.

### Text editing in a pane

`textbox()` maps to the input line, caique's line editor hosted in one pane (the `input`
option of `open()`). `textarea()`, a multi-line editor inside the layout, does not map:
prompts stay with caique, outside a pane. See
[blessed's section](/docs/coming-from/blessed#text-editing-in-a-pane).

### Legacy Windows consoles

controlroom handles no Windows legacy console quirks beyond what Node's own terminal handling
does.

## Is controlroom compatible with neo-blessed?

**No, by design.** There is no drop-in and nothing is graded, for neo-blessed or for blessed.

## What you gain over neo-blessed

A static projection of every screen for a pipe, CI and a screen reader, NDJSON events on
stderr under `--json`, no wait for a key that nobody can press, an inline mode under the
program's own output, and one render engine shared with flagstaff.
[blessed's page](/docs/coming-from/blessed#what-you-gain-over-blessed) has each. Nothing
about neo-blessed's own output or size has been measured here.

## When to switch from neo-blessed

Switch a screen if it has to work for a pipe, CI, a screen reader or an agent as well as for a
person at a terminal. Stay on neo-blessed if you depend on the mouse or on multi-line editing
inside the screen.

---

# Coming from terminal-kit

> Move a terminal-kit full-screen program to controlroom, the burgee family's terminal-kit alternative: fullscreen, grabInput, on('key'), menus and screen buffers mapped onto open(), keymaps and flagstaff panes, what does not map, and what burgee migrate reports.

Source: https://burgee.interlace.tools/docs/coming-from/terminal-kit

**controlroom** is the burgee family's **terminal-kit alternative** for keyboard-driven
terminal programs, inline or full-screen. `open()`, layout, tabs and keymaps, the input line
and plugins all ship, since 0.2.0.

terminal-kit is several libraries in one. Its styled output, spinners, progress bars and
yes/no questions map to other packages: roundel for colour, flagstaff for spinners and
progress, caique for questions. This page is about the part that takes over the screen and
reads keys, which is controlroom's. If you only draw inline output, start at
[Which one do I need?](/docs/packages#which-one-do-i-need)

## Migrate from terminal-kit: not one import

There is no `controlroom/terminal-kit`, and none is planned: its surface is too large to
reproduce honestly, so moving is a rewrite of each screen, not of the import line.
`burgee migrate` finds the terminal-kit sites in your project and names the section of this
page that covers each one:

```bash
npx burgee migrate --dry-run --json
```

It reports and never rewrites: a terminal-kit screen and a controlroom screen are different
shapes, so each one is a decision, not a substitution. For this program:

```js
const term = require('terminal-kit').terminal;

term.fullscreen(true);
term.grabInput(true);
term.on('key', (name) => {
  if (name === 'CTRL_C') term.processExit(0);
});
term.singleColumnMenu(['build', 'test'], (error, response) => {});
```

the report's `guided` list reads:

```json
[
  { "file": "src/ui.js", "line": 1, "from": "terminal-kit", "pattern": "import", "guide": "https://burgee.interlace.tools/docs/coming-from/terminal-kit#the-mapping" },
  { "file": "src/ui.js", "line": 3, "from": "terminal-kit", "pattern": "alternate-screen", "guide": "https://burgee.interlace.tools/docs/coming-from/terminal-kit#alternate-screen" },
  { "file": "src/ui.js", "line": 4, "from": "terminal-kit", "pattern": "key", "guide": "https://burgee.interlace.tools/docs/coming-from/terminal-kit#key-handling" },
  { "file": "src/ui.js", "line": 5, "from": "terminal-kit", "pattern": "key", "guide": "https://burgee.interlace.tools/docs/coming-from/terminal-kit#key-handling" },
  { "file": "src/ui.js", "line": 8, "from": "terminal-kit", "pattern": "list", "guide": "https://burgee.interlace.tools/docs/coming-from/terminal-kit#list" }
]
```

A site is reported only when its receiver came from terminal-kit in the same file: the
`terminal` or `realTerminal` the module hands out, one made by `createTerminal()`, or a
`ScreenBuffer`. A `term` passed in from another file is not followed. The exit code stays 0,
because nothing was refused. The [Migrate](/docs/migrate) page has the whole report.

## The mapping

| terminal-kit | controlroom |
| :-- | :-- |
| `require('terminal-kit').terminal` | `open(runtime, { screen })` |
| `term.fullscreen(true)` | `open(runtime, { screen: 'alternate' })` |
| `term.fullscreen(false)` | `close()` on what `open()` returned, or any exit |
| `term.grabInput(true)` | nothing: raw mode is taken once by the screen |
| `term.on('key', fn)` | an entry in a keymap, which is data, and `onAction` |
| `new termkit.ScreenBuffer()` and `draw()` | nothing: an `update()` repaints |
| `term.moveTo(x, y)` with text | a pane in a layout tree, holding a flagstaff component |
| `term.singleColumnMenu()` | flagstaff's `tasks` for a list you show; caique's `select` for a pick |
| `term.on('resize', fn)` | nothing: the screen lays out again |
| `term.inputField()` | the input line: caique's line editor in a pane |
| `term.grabInput({ mouse })`, `on('mouse')` | nothing |

### Screen

terminal-kit hands you a terminal and leaves the rest to you. controlroom's
`open(runtime, { screen: 'alternate' })` is one call for the alternate screen, raw mode, the
layout and the restore. It takes the terminal **only** when roundel's output policy says
`tty` and stdin can go raw. In every other mode it opens a static screen instead, so the same
program runs in a pipe, in CI and under `--json`. `runtime` is the structural runtime the
family's packages take instead of reading `process`; `processRuntime()` is the real one.

```js title="status.mjs"
import { open, processRuntime } from 'controlroom';

/** The smallest flagstaff component: its state is the text it shows. */
const text = { name: 'text', static: (s) => s };

const screen = open(processRuntime(), {
  screen: 'alternate',
  json: process.argv.includes('--json'),
  layout: 'status',
  keymap: { r: 'refresh', q: 'quit', 'ctrl+c': 'quit' },
  panes: { status: { component: text, state: 'cache: stale', label: 'Status' } },
  onAction(action, s) {
    if (action === 'refresh') s.update('status', 'cache: fresh');
  },
});

// Off a terminal nobody can press `r`, so the program does what the key would have done.
if (!screen.interactive) {
  screen.dispatch('refresh');
  screen.close();
}
```

On a terminal it waits for `r`, and `q` or Ctrl+C closes it. Piped:

```text title="node status.mjs | cat"
Status
cache: stale
cache: fresh
```

`screen: 'inline'`, the default, draws a live region under the program's own output instead,
which stays in the scrollback.

`burgee migrate` reports `createTerminal()`, `new termkit.ScreenBuffer()` and
`new termkit.ScreenBufferHD()` here, and follows `terminal` and `realTerminal` to their uses.

### Box

terminal-kit has no box: a program moves the cursor and writes, or fills a `ScreenBuffer`.
In controlroom a region of the screen is a pane, a name in one layout tree of rows and
columns with fixed, fractional (`{ fr, min }`) and fit-to-content sizes. What a pane draws is
any flagstaff component; a border, padding and a title come from flagstaff's `boxComponent`.

```js
import { layout } from 'controlroom';

const tree = {
  direction: 'column',
  parts: [
    { content: { direction: 'row', parts: [{ size: { fr: 1, min: 20 }, content: 'learn' }, { size: { fr: 2 }, content: 'tasks' }] } },
    { size: 8, content: 'logs' },
  ],
};
layout(tree, { x: 0, y: 0, width: 100, height: 30 }).get('tasks');
// { x: 34, y: 0, width: 66, height: 22 }
```

No absolute `moveTo()` survives the move: positions are arithmetic over the terminal's size,
done again on every resize. `layout()` is the function `open()` calls on every paint.

### List

`singleColumnMenu()`, `singleLineMenu()`, `singleRowMenu()` and `gridMenu()` each ask the
user to pick. A pick is a prompt, and prompts are caique's: `select`, asked before or after
the screen, not inside it. No pane component picks. A list you only **show**, such as steps
with a state each, is flagstaff's `tasks` in a pane. `burgee migrate` reports the four menus
here.

### Key handling

terminal-kit has you call `grabInput(true)` and then subscribe to `on('key')` with a function
that switches on the key name. controlroom takes raw mode once for the screen's whole life,
hands it back on every exit, and binds each key to an **action name** in a keymap that is
plain data. The screen's tabs, focus and collapsed panes move through a reducer, and your
`onAction(action, screen)` sees every action after it. The hint line is generated from the
same keymap.

```js
import { hints, initial, reduce } from 'controlroom';

const keymap = { left: 'tab.prev', right: 'tab.next', s: 'toggle:status', q: 'quit', 'ctrl+c': 'quit' };
const labels = { 'tab.prev': 'switch tab', 'tab.next': 'switch tab', 'toggle:status': 'toggle status', quit: 'quit' };

let state = initial(['Status', 'Tail logs'], ['learn', 'tasks']);
state = reduce(state, keymap.right); // state.active is 1: the second tab
hints(keymap, labels); // '←→ switch tab  s toggle status  q/^C quit'
```

An action the reducer does not know, such as `quit` here, leaves the state alone and is the
program's own to handle; a live screen closes on `quit`. Key names are spelled as caique's
key decoder spells them:

| terminal-kit | controlroom |
| :-- | :-- |
| `CTRL_C` | `ctrl+c` |
| `SHIFT_TAB` | `shift+tab` |
| `LEFT`, `RIGHT`, `ESCAPE` | `left`, `right`, `escape` |

Keys are read only when stdout is a terminal and stdin can go raw, and there is no
`grabInput()` to forget to release. Everywhere else `screen.dispatch(action)` runs an action
as if its key had been pressed.

`burgee migrate` reports `grabInput()` and every `on()` or `once()` whose event name starts
with `key`.

### Render loop

A terminal-kit program writes as it goes, or fills a `ScreenBuffer` and calls
`draw({ delta: true })` when it decides to. controlroom has no draw call to make.
`update(pane, state)` repaints: the layout is composed from every pane's frame and handed to
flagstaff's frame writer, which writes only the rows that changed, inside one
synchronized-output block, and the screen is laid out again on resize. controlroom never
writes to the terminal itself. `burgee migrate` reports each `draw()` on a screen buffer.

### Alternate screen

`fullscreen(true)` enters the alternate screen and `fullscreen(false)` leaves it.
controlroom's is the `screen: 'alternate'` option. The alternate screen, the hidden cursor,
raw mode and bracketed paste are each entered through closeout with their undo registered in
the same call, so `close()`, Ctrl+C, a signal and a throw all hand the terminal back. The
alternate screen has no scrollback, so text given to `commit()` there is kept and handed to
the main screen when the screen closes. `burgee migrate` reports each `fullscreen()` here.

## What does not map

These are out of scope, so a program that depends on them should stay on terminal-kit.

### Mouse

`grabInput({ mouse: 'button' })` and `on('mouse')` have no controlroom equivalent, and none
is planned. `burgee migrate` reports the `mouse` option and each mouse subscription it can
see.

### Text editing in a pane

`inputField()` maps to the **input line**: caique's line editor hosted in one pane, with
history, completion and pasted text arriving whole. Keys go to it while it has focus and fall
through to the keymap when it does not use them, and in a pipe each line of stdin is one
entry. It is the `input: { editor, pane, onSubmit, onEnd }` option of `open()`.
`burgee migrate` reports each `inputField()` here. A multi-line editor or a form inside the
layout does not map: a question asked once is caique's prompt.

### Legacy Windows consoles

controlroom handles no Windows legacy console quirks beyond what Node's own terminal handling
does. If your program relies on terminal-kit's handling of a particular terminal, check that
before you move it.

terminal-kit's document model, images and terminal capability database have no controlroom
counterpart either.

## Is controlroom compatible with terminal-kit?

**No, by design.** There is no drop-in and nothing is graded: no terminal-kit suite runs
against controlroom, and none will, because the API is not being reproduced. The
[Compatibility](/docs/compatibility) page grades controlroom's drop-in for **ink**,
`controlroom/ink`, by ink 8.0.0's own suite. It has no terminal-kit row.

## What you gain over terminal-kit

- **Every caller gets an answer, not just a terminal.** Off a terminal a screen prints each
  pane's static projection under its label, with no escape byte, no carriage return and no
  cursor movement, and only the lines that changed on each update. Tabs hide nothing, and a
  `liveOnly` pane such as the hint line is not printed.
- **`--json` is an event stream.** One NDJSON event per change on stderr, named after the
  pane, with stdout left for the program's result.
- **It never waits for a key nobody can press.** Behind a pipe, in CI or with `< file`, a
  screen reads no keys, and `dispatch()` is what the program has instead.
- **The terminal comes back.** Leaving the alternate screen and raw mode is registered with
  closeout when they are entered, not left to an exit handler the program has to write.
- **One render engine.** The spinner in a pane is the same flagstaff component, drawn by the
  same frame loop, as the spinner in an ordinary CLI.

This page does not say what terminal-kit writes to a pipe or under CI, and makes no size or
speed comparison against terminal-kit: none has been measured here.

## When to switch from terminal-kit

Switch a screen if its output has to work for a pipe, CI, a screen reader or an agent as well
as for a person at a terminal. The inline parts of terminal-kit — colour, spinners, progress
bars, questions — move to roundel, flagstaff and caique, a file at a time. Stay on
terminal-kit if you depend on the mouse, on multi-line editing in place, or on its document
model.

---

# burgee vs the alternatives

> Measured against commander, yargs, oclif, cac and citty — every capability row marked built is in the package today, with its tests.

Source: https://burgee.interlace.tools/docs/comparison

**This page is maintained by hand, and that is the reason to distrust it most.** Four of
its rows disagreed with the suite that now measures them — an installed size 5.4x under,
an import cost that flattered us by 12 ms, a claim that burgee landed level with cac
against a measured 1.45x, and a compatibility count of 1,361 that has been
1,360 since the oracle's baseline was set. [Benchmarks](/docs/benchmarks) is generated from `npm run bench` and is the
authority; this page exists to put six frameworks in one table, which that one does not
do, and every cell here now says where it comes from.

- **⚙️ measured** by `npm run bench` on this repo, all four packages in one run on one
  machine, at the date below.
- **📖 surveyed** in [`competitor-landscape.md`](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/research/competitor-landscape.md)
  §2 on a different machine at a different time. Never compare a ⚙️ against a 📖 — that is
  a comparison between two machines.

## Measured

⚙️ rows: 2026-10-19 (`66e4611`), a GitHub Actions runner (AMD EPYC 7763, 4 cores), linux/x64, Node
24.13, 52 interleaved spawns per variant. Milliseconds are a property of that machine, so the deltas below are for reading,
never for gating; the machine-independent figure is the ratio on
[Benchmarks](/docs/benchmarks).

| | **burgee** | commander | yargs | @oclif/core | cac | citty |
| :--- | ---: | ---: | ---: | ---: | ---: | ---: |
| Downloads / week | new | 508.2M | 259.3M | 10.9M | 49.4M | 30.5M |
| Runtime dependencies | **5**, none outside the burgee family | 0 | 6 | **18** | 0 | 0 |
| Installed size ⚙️ | 1607 KB | 203 KB | 515 KB | 912 KB 📖 | 40 KB | 52 KB 📖 |
| Full CLI run over bare node ⚙️ | +19.1 ms | +15.3 ms | +77.1 ms | +131 ms 📖 | +4.1 ms | +6 ms 📖 |

Three things in that table got worse when they were measured rather than asserted, and
they stay in it.

**Installed size.** burgee installs at **1607 KB**. It is our largest number, it is our least
flattering one, and it has now been wrong on this page twice in opposite directions.

First it said 104 KB, a guess at the tarball rather than a measurement. That was corrected
to **561 KB** on 2026-09-09 — the real `npm pack` unpacked size, which is what lands in a
user's `node_modules` — and then the package grew to **2.3x that figure** while the cell sat
still, because the cell was read from a *published* measurement rather than from a fresh
install. Every check on this page compared the page against that file and stayed green.

Fixed 2026-09-16: the row is now measured against the tree by CI on every run, so it cannot
fall behind again. It is checked there and not on a developer's laptop for a reason worth
stating, since it is the same class of mistake: the walk starts at a workspace link, so
locally it counts a developer's dev dependencies too and reads several hundred KB more for the
same commit. The cell is whatever `npm i burgee` puts on disk on the runner, and nothing else.

**85 KB of it arrived on 2026-09-17 and is worth naming.** `burgee/commander` now spawns
sub-binaries through `bellpull` instead of `node:child_process`, so burgee installs bellpull's
whole package — 86,113 bytes. What it buys is a Windows subcommand that actually works: upstream
commander sends every Windows spawn through `node`, which is a workaround for `spawn` not
searching `PATHEXT`, and it is simply wrong for a subcommand that is a `.cmd`, a `.bat`, or has
a shebang that is not node. The check on this row is what surfaced the cost, which is the
argument for the check.

**24 KB more arrived on 2026-09-30:** `seniority/yaml` (24,226 bytes), the YAML parser that
`seniority`'s cosmiconfig drop-in needs to read the YAML files cosmiconfig reads. burgee never
loads it — no module on burgee's path imports it, and its bundled column did not move — but it
is on disk.

**About 90 KB left on 2026-10-11.** Every family package published a declaration file for
every module, and a TypeScript consumer can only open the ones an `exports` entry reaches.
burgee alone shipped 35 that none does, 76,504 bytes of them (`migrate.d.ts` was the largest).
The build now prunes them by the closure the TypeScript compiler computes from the entry
points, and a check fails if any shipped declaration imports one that was not shipped
([D-20261011](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/decisions/D-20261011-tarball-unreachable-declarations.md)).

It buys no dependency outside the burgee family and seven drop-in front ends. It is still 1607 KB, and the
bundled column on [Benchmarks](/docs/benchmarks) — what an application actually grows by —
is the number to judge us on. That one is over its own ceiling too, and says so.

**Speed.** This page previously ran two rows, an import cost and a full run, with burgee's
cells in both unsourced. The suite times one thing, a full CLI run as a process, so there
is one row. burgee does **not** land level with cac: it starts at **1.47x** cac's cold
start against a published target of at or below cac, and that target is recorded as not
met. It read 1.32x on 2026-09-09 and 1.56x on 2026-10-08, and CI runs since 2026-10-06 have
read 1.47x to 1.56x: burgee's start-up got slower in that month, and this page says so rather
than keeping the older figure. Since D-157 the gate is what is reachable: a downward-only ratchet at 1.55x
cac, set from CI's own spread and only ever lowered, which it still meets. The `burgee/yargs`
drop-in starts at 0.64x yargs (0.82x on 2026-09-09). The `burgee/commander` drop-in starts at
**1.07x** commander (1.18x on 2026-10-08, 1.08x on 2026-09-09).

These are the figures from the CI runner, which is where the suite now publishes from: the
same commit measured eleven times there put `burgee ÷ cac` inside 2.3%, where a developer
laptop under load spread the same ratio from 1.351 to 1.957 in a single day. The absolute
milliseconds are a property of that machine and are not comparable with the two 📖 columns,
which come from a survey on somebody else's. **The ratios are what the gates and bands
watch**, because a ratio taken between two spawns in the same run cancels the machine out.

Moving to that machine did not uniformly flatter us. `burgee ÷ cac` improved from 1.45x to
1.32x and commander went from a small loss to a level result; `burgee/yargs ÷ yargs` moved
against us, from 0.69x to 0.82x. The machine was chosen for its variance, before these
numbers were read.

burgee's speed comes from `node:util.parseArgs` being in the standard library, not from a
faster language: burgee is TypeScript, exactly like commander and yargs. On this run it buys
a lead over yargs, and neither parity with commander nor a lead over cac.

`@oclif/core`'s **131 ms** is a surveyed number, not one this suite reproduces, and it is
carried here rather than dropped because eighteen runtime dependencies against none outside the burgee family is the
comparison this table exists for. Treat it as the survey's, not as ours.

## Capabilities, with evidence

burgee against commander, yargs and meow, the three frameworks compat-oracle grades its drop-in paths against.
Every mark links to its evidence — a test in this repository for burgee, and for the others the
source file at the version the oracle grades, or that framework's own test suite — and
`scripts/capabilities-lock.test.ts` fails the build when a cited test or quoted source stops
saying what the cell claims. A row is here only when every cell of it can be proved.

✓ yes · ◐ partial (what is missing is said) · ✗ no · — does not apply. Every cell links to its evidence: our test or grade, or the incumbent’s source at the version compat-oracle grades.

### Agents and automation

| Capability | **burgee** | commander | yargs | meow |
| :-- | :-- | :-- | :-- | :-- |
| **`--json` envelope** — Every command answers `--json` with one `{ ok, data }` or `{ ok, error }` document on stdout, from the same declaration as its text output. | [✓](https://github.com/ofri-peretz/burgee/blob/main/packages/burgee/src/shape.test.ts) | [✗](https://cdn.jsdelivr.net/npm/commander@15.0.0/lib/command.js) | [✗](https://cdn.jsdelivr.net/npm/yargs@18.2.0/build/lib/yargs-factory.js) | [✗ meow returns the parsed flags to the program; it writes no output format of its own.](https://github.com/sindresorhus/meow/blob/v14.1.0/source/index.js) |
| **`--schema` (the CLI as data)** — Any program prints its commands, arguments, options, choices, defaults and effects as JSON, without running a handler. | [✓](https://github.com/ofri-peretz/burgee/blob/main/packages/burgee/src/schema.test.ts) | [✗](https://cdn.jsdelivr.net/npm/commander@15.0.0/lib/command.js) | [✗](https://cdn.jsdelivr.net/npm/yargs@18.2.0/build/lib/yargs-factory.js) | [✗](https://github.com/sindresorhus/meow/blob/v14.1.0/source/index.js) |
| **`--mcp` (an MCP server)** — Any program serves its commands as MCP tools over stdio, so an agent can call them without a wrapper. | [✓](https://github.com/ofri-peretz/burgee/blob/main/packages/burgee/src/mcp.test.ts) | [✗](https://cdn.jsdelivr.net/npm/commander@15.0.0/lib/command.js) | [✗](https://cdn.jsdelivr.net/npm/yargs@18.2.0/build/lib/yargs-factory.js) | [✗](https://github.com/sindresorhus/meow/blob/v14.1.0/source/index.js) |
| **Agent detection** — A program run by a coding agent knows which agent it is and turns interaction off, even when a terminal is attached. | [✓](https://github.com/ofri-peretz/burgee/blob/main/packages/burgee/src/agent.test.ts) | [✗ No agent variable is read anywhere in the installed package.](https://cdn.jsdelivr.net/npm/commander@15.0.0/lib/command.js) | [✗ No agent variable is read anywhere in the installed package.](https://cdn.jsdelivr.net/npm/yargs@18.2.0/build/lib/yargs-factory.js) | [✗](https://github.com/sindresorhus/meow/blob/v14.1.0/source/index.js) |
| **Exit-code contract** — Usage, config, auth, cancellation and runtime failures each exit with their own fixed code, so a script can branch on the code instead of the message. | [✓](https://github.com/ofri-peretz/burgee/blob/main/packages/burgee/src/exit-code.test.ts) | [✗ Every error commander raises, an unknown option included, exits 1; a program can pass its own code to error(), but there is no set of named codes.](https://cdn.jsdelivr.net/npm/commander@15.0.0/lib/command.js) | [✗ Every failure yargs reports, usage or handler, exits 1.](https://cdn.jsdelivr.net/npm/yargs@18.2.0/build/lib/usage.js) | [◐ only incorrect usage has its own code (2); there is none for config, auth or cancellation](https://github.com/sindresorhus/meow/blob/v14.1.0/source/index.js) |

### Shell and terminal

| Capability | **burgee** | commander | yargs | meow |
| :-- | :-- | :-- | :-- | :-- |
| **Completions for bash, zsh, fish and PowerShell** — Every program prints a completion script for each of the four shells, generated from the same declaration as its help. | [✓](https://github.com/ofri-peretz/burgee/blob/main/packages/burgee/src/completions-shells.test.ts) | [✗](https://cdn.jsdelivr.net/npm/commander@15.0.0/lib/command.js) | [◐ bash, zsh and fish only; no PowerShell script](https://cdn.jsdelivr.net/npm/yargs@18.2.0/build/lib/completion-templates.js) | [✗](https://github.com/sindresorhus/meow/blob/v14.1.0/readme.md) |
| **Cleanup on Ctrl+C** — A cleanup a command registered runs when the user presses Ctrl+C, and the process then ends by the signal, which a shell reports as 130. | [✓](https://github.com/ofri-peretz/burgee/blob/main/packages/burgee/src/pty-signal.test.ts) | [✗ commander's only signal listeners forward the signal to an executable subcommand's child process.](https://cdn.jsdelivr.net/npm/commander@15.0.0/lib/command.js) | [✗ No signal is handled anywhere in the installed package.](https://cdn.jsdelivr.net/npm/yargs@18.2.0/build/lib/yargs-factory.js) | [— meow parses and returns; it runs no command, so there is nothing of its own to clean up.](https://github.com/sindresorhus/meow/blob/v14.1.0/source/index.js) |
| **No help screen on a runtime error** — A command that fails prints its error, not the usage text, so the message is not buried under help it did not ask for. | [✓](https://github.com/ofri-peretz/burgee/blob/main/packages/burgee/src/define-error.test.ts) | [✓ Help after an error is opt-in and covers commander's own usage errors; an action's error is not caught at all and escapes with its stack.](https://cdn.jsdelivr.net/npm/commander@15.0.0/lib/command.js) | [◐ a rejected handler prints the help screen by default; showHelpOnFail(false) stops that only by stopping it for usage errors too](https://cdn.jsdelivr.net/npm/yargs@18.2.0/build/lib/usage.js) | [— meow parses and returns; it runs no command, so a runtime error never passes through it.](https://github.com/sindresorhus/meow/blob/v14.1.0/source/index.js) |

### Configuration

| Capability | **burgee** | commander | yargs | meow |
| :-- | :-- | :-- | :-- | :-- |
| **Config, env and flag layers with the winning source named** — Values resolve flag over env over config file over package.json over default, and `config explain` or `--explain <option>` says which layer won. | [✓](https://github.com/ofri-peretz/burgee/blob/main/packages/burgee/src/config-explain.test.ts) | [◐ reads no config file; a program loads one itself and sets each value with the 'config' source](https://cdn.jsdelivr.net/npm/commander@15.0.0/lib/command.js) | [◐ no record of which layer (flag, env, config) supplied a value](https://cdn.jsdelivr.net/npm/yargs@18.2.0/build/lib/yargs-factory.js) | [✗ meow reads package.json for the version and description only; it has no env or config-file layer.](https://github.com/sindresorhus/meow/blob/v14.1.0/readme.md) |
| **`--version` from package.json** — `--version` prints the version from the package.json that owns the entry file, unless the program declares its own. | [✓](https://github.com/ofri-peretz/burgee/blob/main/packages/burgee/src/env.test.ts) | [✗ The program passes the version string to .version() itself.](https://cdn.jsdelivr.net/npm/commander@15.0.0/lib/command.js) | [✓](https://cdn.jsdelivr.net/npm/yargs@18.2.0/build/lib/yargs-factory.js) | [✓](https://github.com/sindresorhus/meow/blob/v14.1.0/readme.md) |

### Compatibility

| Capability | **burgee** | commander | yargs | meow |
| :-- | :-- | :-- | :-- | :-- |
| **Passes commander's own test suite** — `burgee/commander` runs commander's own tests at v15.0.0, unedited apart from the import, so a commander program keeps working after the import changes. | [✓ 1,360 / 1,360 of its own tests](https://github.com/ofri-peretz/burgee/blob/main/packages/compat-oracle/baseline/commander.json) | [✓](https://github.com/ofri-peretz/burgee/blob/main/packages/compat-oracle/vendor/commander/tests/command.action.test.js) | [— A different API; commander's suite does not apply to it.](https://cdn.jsdelivr.net/npm/yargs@18.2.0/build/lib/yargs-factory.js) | [— A different API; commander's suite does not apply to it.](https://github.com/sindresorhus/meow/blob/v14.1.0/readme.md) |
| **Passes yargs' own test suite** — `burgee/yargs` runs yargs' own tests at v18.2.0, unedited apart from the import, so a yargs program keeps working after the import changes. | [✓ 816 / 816 of its own tests](https://github.com/ofri-peretz/burgee/blob/main/packages/compat-oracle/baseline/yargs.json) | [— A different API; yargs' suite does not apply to it.](https://cdn.jsdelivr.net/npm/commander@15.0.0/lib/command.js) | [✓ its own suite; the oracle's control run is 814 / 816, because two usage tests read the version from the nearest package.json, which inside a vendored copy is not yargs'](https://github.com/ofri-peretz/burgee/blob/main/packages/compat-oracle/vendor/yargs/test/yargs.mjs) | [— A different API; yargs' suite does not apply to it.](https://github.com/sindresorhus/meow/blob/v14.1.0/readme.md) |
| **Passes meow's own test suite** — `burgee/meow` runs meow's own tests at v14.1.0, unedited apart from the import, and the count it passes is published. | [◐ 146 / 148 of its own tests](https://github.com/ofri-peretz/burgee/blob/main/packages/compat-oracle/baseline/meow.json) | [— A different API; meow's suite does not apply to it.](https://cdn.jsdelivr.net/npm/commander@15.0.0/lib/command.js) | [— A different API; meow's suite does not apply to it.](https://cdn.jsdelivr.net/npm/yargs@18.2.0/build/lib/yargs-factory.js) | [✓ The oracle's control run is 146 / 148: one case imports meow's rollup build and one needs normalize-package-data, neither present in the vendored copy.](https://github.com/ofri-peretz/burgee/blob/main/packages/compat-oracle/vendor/meow/test/test.js) |

## Capabilities across six frameworks

This table is older and hand-maintained, and covers oclif, cac and citty, which the table above
does not grade. Where the two disagree, the one above is the one with evidence: this table said
commander dumps its help on a runtime error, and commander's own source says help after an error
is off by default.

| | **burgee** | commander | yargs | oclif | cac | citty |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| One file, no build step | ✅ *(enforced by test)* | ✅ | ✅ | ❌ scaffold | ✅ | ✅ |
| **Plugins** that add commands | ✅ **built** | ❌ *(RFC #2505, closed unlanded)* | ❌ | ✅ | ❌ | ❌ |
| Plugins on *commander* syntax | ✅ **built** | — | — | — | — | — |
| `--json` envelope | ✅ **built** | ❌ | ❌ | partial | ❌ | ❌ |
| Exit-code contract | ✅ **built** | ❌ | ❌ | partial | ❌ | ❌ |
| No help dumped on a runtime error | ✅ **built** | ✅ | ❌ | ❌ | ❌ | ❌ |
| Weight budget per entry point | ✅ **built** | ❌ | ❌ | ❌ | ❌ | ❌ |
| commander compatibility | ✅ 1,360 / 1,360 of commander's own tests | — | ❌ | ❌ | ❌ | ❌ |
| yargs compatibility | ✅ 816 / 816 of yargs' own tests | ❌ | — | ❌ | ❌ | ❌ |
| `--schema` (the CLI as data) | ✅ **built** | ❌ | ❌ | manifest | ❌ | ❌ |
| `--mcp` (an MCP server) | ✅ **built** | ❌ | ❌ | ❌ | ❌ | ❌ |
| Shell completions | ✅ **built** | ❌ | partial | ✅ | ❌ | partial |
| Types derived from one schema | ✅ **built** | partial | partial | ✅ | partial | ✅ |

✅ built · 🔨 in progress

**Plugins** means a package that adds commands to a program it did not write, which is what
oclif's plugins and burgee's do. citty 0.2.2 has a `plugins` option, but each one is a pair
of `setup` and `cleanup` hooks run around a command and adds no command, so its cell stays
❌.

## The three that matter

**Plugins.** commander has no plugin system — its RFC has been open for years — and yargs
has none either. burgee has one, and it works on a program written in *commander's* syntax:
change one import and you gain a capability commander cannot sell you at any price.

**Nothing you rely on breaks.** Compatibility is graded by commander's own 1,360 tests and
yargs' 816, run in our CI, published as a pass rate that only goes up. Not the word
"compatible" — a number you can check. (This paragraph said 1,215 and the table said 1,361;
both were wrong, and the count the oracle's baseline actually holds is 1,360. It is on
[Benchmarks](/docs/benchmarks), where it is read from the oracle rather than retyped.)

**One declaration, every surface.** Help, `--json`, `--schema`, `--mcp`, completions and
types are all projections of the same manifest, so they cannot drift, and adding the next
one is an emitter rather than a feature.

## What we do not have

**Users.** commander and yargs do 767M downloads a week between them; burgee is days old.
Every number above is real and none of it matters until someone installs it. The
compatibility burn-down is published from the first commit precisely so that gap is visible
rather than glossed.

## Reproducing

The ⚙️ rows come from the suite, not from a shell loop, because a shell loop measures
whatever else the machine was doing:

```bash
git clone https://github.com/ofri-peretz/burgee && cd burgee
npm install && npx turbo run build
npm run bench -- --check
```

That writes `benchmarks/results/cli-benchmarks/<date>.json`, which carries every number on
[Benchmarks](/docs/benchmarks) along with the resolved version and path of every package it
measured. The 📖 rows are not reproduced by it; they are
[`competitor-landscape.md`](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/research/competitor-landscape.md)
§2's, taken on a different machine.

---

# Compatibility

> Each host's own test suite, run against burgee in CI. A published pass rate that only goes up — never the word "compatible".

Source: https://burgee.interlace.tools/docs/compatibility

Generated by `npm run compat:page` from the oracle's last run on 2026-10-19.
Do not edit by hand.

Each row is the **host's own test suite** — vendored, unmodified apart from the import
specifier — pointed at burgee's front-end through a generated shim. The *control* column is
the same suite pointed at the real host: it proves the gate works before it grades anything
of ours, and it is the reference total every rate is measured against. A file that fails to
import registers as one test instead of its twenty, so measuring against registered tests
would flatter a partial implementation; measuring against the control's total does not.

| Host | Front-end | burgee | rate | control | rate | internals (burgee) | internals (control) |
| :--- | :--- | ---: | ---: | ---: | ---: | ---: | ---: |
| [**commander**](https://burgee.interlace.tools/docs/vs/commander) | `burgee/commander` | 1360 / 1360 | 100.0% | 1360 / 1360 | 100.0% | 12 / 12 | 12 / 12 |
| **extra-typings** | `burgee/commander/extra-typings` | 369 / 369 | 100.0% | 369 / 369 | 100.0% | — | — |
| [**yargs**](https://burgee.interlace.tools/docs/vs/yargs) | `burgee/yargs` | 816 / 816 | 100.0% | 814 / 816 | 99.8% | 23 / 23 | 23 / 23 |
| [**chalk**](https://roundel.interlace.tools/docs/coming-from/chalk) | `roundel/chalk` | 59 / 59 | 100.0% | 59 / 59 | 100.0% | — | — |
| **picocolors** | `roundel` | 1 / 1 | 100.0% | 1 / 1 | 100.0% | — | — |
| **supports-color** | `roundel` | 55 / 55 | 100.0% | 55 / 55 | 100.0% | — | — |
| **yoctocolors** | `roundel` | 78 / 78 | 100.0% | 78 / 78 | 100.0% | — | — |
| [**ora**](https://flagstaff.interlace.tools/docs/coming-from/ora) | `flagstaff/ora` | 99 / 99 | 100.0% | 99 / 99 | 100.0% | — | — |
| [**log-update**](https://flagstaff.interlace.tools/docs/coming-from/log-update) | `flagstaff/log-update` | 99 / 99 | 100.0% | 99 / 99 | 100.0% | — | — |
| [**boxen**](https://flagstaff.interlace.tools/docs/coming-from/boxen) | `flagstaff/boxen` | 213 / 213 | 100.0% | 213 / 213 | 100.0% | — | — |
| [**cli-table3**](https://flagstaff.interlace.tools/docs/coming-from/cli-table3) | `flagstaff/cli-table3` | 29 / 29 | 100.0% | 29 / 29 | 100.0% | 103 / 104 | 103 / 104 |
| [**string-width**](https://linegauge.interlace.tools/docs/coming-from/string-width) | `linegauge` | 233 / 233 | 100.0% | 233 / 233 | 100.0% | — | — |
| [**strip-ansi**](https://linegauge.interlace.tools/docs/coming-from/strip-ansi) | `linegauge/strip` | 8 / 8 | 100.0% | 8 / 8 | 100.0% | — | — |
| [**cross-spawn**](https://bellpull.interlace.tools/docs/coming-from/cross-spawn) | `bellpull/cross-spawn` | 68 / 68 | 100.0% | 68 / 68 | 100.0% | — | — |
| [**which**](https://bellpull.interlace.tools/docs/coming-from/which) | `bellpull` | 5 / 5 | 100.0% | 5 / 5 | 100.0% | — | — |
| [**execa**](https://bellpull.interlace.tools/docs/coming-from/execa) | `bellpull` | 0 / 1360 | 0.0% | 1360 / 1360 | 100.0% | — | — |
| [**rc**](https://seniority.interlace.tools/docs/coming-from/rc) | `seniority/rc` | 1 / 1 | 100.0% | 1 / 1 | 100.0% | — | — |
| [**wrap-ansi**](https://linegauge.interlace.tools/docs/coming-from/wrap-ansi) | `linegauge/wrap` | 85 / 85 | 100.0% | 85 / 85 | 100.0% | — | — |
| [**slice-ansi**](https://linegauge.interlace.tools/docs/coming-from/slice-ansi) | `linegauge/slice` | 104 / 104 | 100.0% | 104 / 104 | 100.0% | — | — |
| **cli-truncate** | `linegauge` | 12 / 12 | 100.0% | 12 / 12 | 100.0% | — | — |
| **widest-line** | `linegauge` | 1 / 1 | 100.0% | 1 / 1 | 100.0% | — | — |
| [**cosmiconfig**](https://seniority.interlace.tools/docs/coming-from/cosmiconfig) | `seniority` | 242 / 243 | 99.6% | 242 / 243 | 99.6% | 10 / 10 | 0 / 10 |
| **lilconfig** | `seniority` | 77 / 77 | 100.0% | 77 / 77 | 100.0% | — | — |
| [**dotenv**](https://seniority.interlace.tools/docs/coming-from/dotenv) | `seniority` | 193 / 193 | 100.0% | 193 / 193 | 100.0% | 4 / 10 | 4 / 10 |
| **find-up** | `seniority` | 104 / 104 | 100.0% | 104 / 104 | 100.0% | — | — |
| [**clack**](https://caique.interlace.tools/docs/coming-from/clack) | `caique/clack` | 16 / 16 | 100.0% | 16 / 16 | 100.0% | — | — |
| **inquirer-prompts** | `caique/inquirer` | 213 / 213 | 100.0% | 213 / 213 | 100.0% | — | — |
| [**inquirer-core**](https://caique.interlace.tools/docs/coming-from/inquirer) | `caique/inquirer` | 41 / 41 | 100.0% | 41 / 41 | 100.0% | — | — |
| **meow** | `burgee/meow` | 146 / 148 | 98.6% | 146 / 148 | 98.6% | — | — |
| [**ansi-escapes**](https://paratext.interlace.tools/docs/coming-from/ansi-escapes) | `paratext` | 4 / 4 | 100.0% | 4 / 4 | 100.0% | — | — |
| [**terminal-link**](https://paratext.interlace.tools/docs/coming-from/terminal-link) | `paratext/terminal-link` | 8 / 8 | 100.0% | 8 / 8 | 100.0% | — | — |
| [**term-img**](https://paratext.interlace.tools/docs/coming-from/term-img) | `paratext/term-img` | 18 / 18 | 100.0% | 18 / 18 | 100.0% | — | — |
| [**restore-cursor**](https://closeout.interlace.tools/docs/coming-from/restore-cursor) | `closeout` | 6 / 6 | 100.0% | 6 / 6 | 100.0% | — | — |
| [**exit-hook**](https://closeout.interlace.tools/docs/coming-from/exit-hook) | `closeout` | 21 / 21 | 100.0% | 21 / 21 | 100.0% | — | — |
| [**signal-exit**](https://closeout.interlace.tools/docs/coming-from/signal-exit) | `closeout` | 134 / 135 | 99.3% | 134 / 135 | 99.3% | — | — |
| **onetime** | `closeout` | 6 / 6 | 100.0% | 6 / 6 | 100.0% | — | — |
| **cli-cursor** | `closeout` | 8 / 8 | 100.0% | 8 / 8 | 100.0% | — | — |
| [**ink**](https://controlroom.interlace.tools/docs/coming-from/ink) | `controlroom/ink` | 1304 / 1304 | 100.0% | 1303 / 1304 | 99.9% | 137 / 148 | 332 / 332 |
| **inkjs-ui** | `controlroom/ink` | 102 / 102 (7 the host marks failing and we pass) | 100.0% | 102 / 102 | 100.0% | — | — |

**Every file of every suite is vendored and run**, and every case that leaves the gate is
named below. Files that import only the host's *internal* modules (its own file layout) are
graded on the informational *internals* columns and never enter the gate: passing them would
mean copying the host, not being compatible with it. A public-surface file that also touches
an internal module stays in the gate, with that import shimmed to our main entry.

### Cases excluded from the gate

A case that cannot fail for any implementation measures nothing, and counting it inflates the
rate. These are excluded by name — they still run, and they still appear in the raw TAP.

| Host | Cases | Why |
| :--- | :--- | :--- |
| **cli-table3** | `test/verify-legacy-compatibility-test.js > verify original cli-table behavior >` | Nine cases that call `commonTests(require('cli-table'))` — the *legacy* incumbent, not the target. They pass whatever `COMPAT_TARGET` names: breaking the target completely still scored 10 / 33, because 27% of the row was a self-test of a third-party package. The other nine, `@api cli-table2 matches verified behavior`, run the same assertions through the shim and are gated. `cli-table` stays a devDependency so the file still loads and the excluded cases still run; they are subtracted from the number, not hidden from the TAP. |
| **execa** | `write to fast-exit subprocess` | `return/early-error.js` runs ``execa(`fast-exit-${process.platform}`, …)`` — a compiled executable upstream ships as `test/fixtures/fast-exit-darwin` (Mach-O) and `fast-exit-linux` (ELF). The vendor step never copies a compiled executable (`binaries.ts`; both are listed under `omitted` in `vendor/execa/PROVENANCE`), so the case cannot pass for anyone and is excluded for ours and the control alike. It was the one case the suite guards with the CPU (`if (!isWindows)`, then `if (arch() === 'x64')`), so the reference is now 1179 on every machine rather than 1180 on ubuntu and 1179 on an arm64 Mac. `bellpull` failed it where it ran, so the target's number does not move. |
| **lilconfig** | `> options > packageProp > string[] with null in the middle > async` | Un-awaited `expect(…).rejects.toThrowError`: the assertion never settles before the case ends, so it passes vacuously under jest and errors under vitest 5. Its `> sync` sibling asserts the same thing synchronously and is gated. |
| **lilconfig** | `> lilconfig > when to throw > non existing file` | Un-awaited `expect(…).rejects.toThrowError`, twice — once against lilconfig, once against cosmiconfig. The `lilconfigSync` case of the same name is synchronous, real, and gated. |
| **lilconfig** | `> lilconfig > when to throw > throws for invalid json` | Un-awaited `expect(…).rejects.toThrowError`. The `lilconfigSync` case of the same name is gated. |
| **lilconfig** | `> lilconfig > when to throw > throws for provided filepath that does not exist` | Un-awaited `expect(…).rejects.toThrowError`. The `lilconfigSync` case of the same name is gated. |
| **lilconfig** | `> lilconfig > when to throw > no loader specified for the search place` | Un-awaited `expect(…).rejects.toThrowError`. The `lilconfigSync` case of the same name is gated. |
| **lilconfig** | `> lilconfig > when to throw > loader is not a function` | Un-awaited `expect(…).rejects.toThrowError`. The `lilconfigSync` case of the same name is gated. |
| **lilconfig** | `> lilconfig > when to throw > throws for empty strings passed to load` | Un-awaited `expect(…).rejects.toThrowError`. The `lilconfigSync` case of the same name is gated. |
| **find-up** | `findup › async (dot file)` | Asserts the nearest `.git` directory is the package's own repository root. A vendored copy has none, so the walk finds whatever repository holds the vendored copy: find-up 8.0.0 fails it here, the same way. |
| **find-up** | `findup › sync (dot file)` | The synchronous twin of `async (dot file)`, with the same expectation of a `.git` at the vendored root, and the same failure against find-up 8.0.0 itself. |
| **clack** | `test/path.test.ts >` | 30 cases. Snapshots of the path prompt's frames, **and** the one file in this suite that fails against clack's own published package here: it mocks `node:fs` with `vi.mock('node:fs')` and no factory, which vitest answers from a `__mocks__` directory beside the project root. Upstream's `__mocks__/fs.cjs` is vendored there by `extraDirs` and is still never loaded — measured 2026-09-14 by putting a `console.error` in it and watching it not print under vitest 5.0.0, which upstream's vitest 3.2.4 does load; a `test.alias` for `node:fs` is no better. So those 30 read the real filesystem, list the real `/tmp`, and diff against a memfs snapshot. That was a `controlFailures` allowance of 30 until 2026-09-20 and is now redundant: the file is subtracted as a drawing like the other sixteen, and an allowance that excuses a case nobody counts is a dial, which is the objection `term-img`'s note already records. |
| **clack** | `test/autocomplete.test.ts >` | 27 cases, 24 snapshot assertions — the autocomplete prompt drawn frame by frame. |
| **clack** | `test/box.test.ts >` | 46 cases, 23 snapshot assertions — box borders, padding and title placement, drawn. |
| **clack** | `test/confirm.test.ts >` | 24 cases, 12 snapshot assertions — the confirm prompt drawn in each of its states. |
| **clack** | `test/date.test.ts >` | 16 cases, 7 snapshot assertions — the date prompt drawn. |
| **clack** | `test/group-multi-select.test.ts >` | 42 cases, 21 snapshot assertions — grouped selection drawn. |
| **clack** | `test/log.test.ts >` | 32 cases, 16 snapshot assertions — the log symbols and their bars, drawn. |
| **clack** | `test/multi-line.test.ts >` | 28 cases, 14 snapshot assertions — the multi-line editor drawn. |
| **clack** | `test/multi-select.test.ts >` | 48 cases, 24 snapshot assertions — multi-selection drawn. |
| **clack** | `test/note.test.ts >` | 18 cases, 9 snapshot assertions — the note box drawn. |
| **clack** | `test/password.test.ts >` | 18 cases, 9 snapshot assertions — the masked prompt drawn. |
| **clack** | `test/progress-bar.test.ts >` | 44 cases, 19 snapshot assertions — the progress bar drawn at each fill. |
| **clack** | `test/select-key.test.ts >` | 24 cases, 12 snapshot assertions — the key-select prompt drawn. |
| **clack** | `test/select.test.ts >` | 40 cases, 20 snapshot assertions — the select prompt drawn. |
| **clack** | `test/spinner.test.ts >` | 60 cases, 28 snapshot assertions — spinner frames, drawn. |
| **clack** | `test/task-log.test.ts >` | 64 cases, 27 snapshot assertions — the task log drawn as it fills and clears. |
| **clack** | `test/text.test.ts >` | 28 cases, 14 snapshot assertions — the text prompt drawn. |
| **clack** | `test/guide.test.ts > guide > no prompt renders a guide when withGuide is globally false` | One case, not a drawing, and it is excluded because it grades a package other than `@clack/prompts`. The test file itself runs `import { updateSettings } from '@clack/core'`, calls it, and asserts that every prompt reads the module-level state of that sibling package. U6 forbids caique a runtime dependency, so no implementation of ours can see that state (D-152). The same setting through the public name is `updateSettings`, which `@clack/prompts` re-exports and `caique/clack` exports. `packages/caique/src/clack.test.ts` holds all twelve prompts to it. The sibling case `no prompt renders a guide when withGuide is false` stays graded and passes. A program that imports `updateSettings` from `@clack/core` directly still reaches clack's state, not caique's (D-20260930-caique-clack-core-exclusion). |
| **inquirer-prompts** | `packages/editor/editor.test.ts > editor prompt > open editor after pressing enter` | Asserts on, and answers through, `vi.mock('@inquirer/external-editor')`'s `editAsync` — a module of the incumbent's tree that `caique/inquirer` does not import (caique takes no dependency outside the burgee family, U6), so the mock can neither observe nor drive any implementation of ours. Excluded for both sides by exact title (D-20261011-inquirer-prompts-editor-mock). |
| **inquirer-prompts** | `packages/editor/editor.test.ts > editor prompt > accepts explicit undefined as default` | Asserts on, and answers through, `vi.mock('@inquirer/external-editor')`'s `editAsync` — a module of the incumbent's tree that `caique/inquirer` does not import (caique takes no dependency outside the burgee family, U6), so the mock can neither observe nor drive any implementation of ours. Excluded for both sides by exact title (D-20261011-inquirer-prompts-editor-mock). |
| **inquirer-prompts** | `packages/editor/editor.test.ts > editor prompt > open editor immediately` | Asserts on, and answers through, `vi.mock('@inquirer/external-editor')`'s `editAsync` — a module of the incumbent's tree that `caique/inquirer` does not import (caique takes no dependency outside the burgee family, U6), so the mock can neither observe nor drive any implementation of ours. Excluded for both sides by exact title (D-20261011-inquirer-prompts-editor-mock). |
| **inquirer-prompts** | `packages/editor/editor.test.ts > editor prompt > allow setting a default value & postfix` | Asserts on, and answers through, `vi.mock('@inquirer/external-editor')`'s `editAsync` — a module of the incumbent's tree that `caique/inquirer` does not import (caique takes no dependency outside the burgee family, U6), so the mock can neither observe nor drive any implementation of ours. Excluded for both sides by exact title (D-20261011-inquirer-prompts-editor-mock). |
| **inquirer-prompts** | `packages/editor/editor.test.ts > editor prompt > allow setting temp file options` | Asserts on, and answers through, `vi.mock('@inquirer/external-editor')`'s `editAsync` — a module of the incumbent's tree that `caique/inquirer` does not import (caique takes no dependency outside the burgee family, U6), so the mock can neither observe nor drive any implementation of ours. Excluded for both sides by exact title (D-20261011-inquirer-prompts-editor-mock). |
| **inquirer-prompts** | `packages/editor/editor.test.ts > editor prompt > handles validation` | Asserts on, and answers through, `vi.mock('@inquirer/external-editor')`'s `editAsync` — a module of the incumbent's tree that `caique/inquirer` does not import (caique takes no dependency outside the burgee family, U6), so the mock can neither observe nor drive any implementation of ours. Excluded for both sides by exact title (D-20261011-inquirer-prompts-editor-mock). |
| **inquirer-prompts** | `packages/editor/editor.test.ts > editor prompt > clear value on failed validation` | Asserts on, and answers through, `vi.mock('@inquirer/external-editor')`'s `editAsync` — a module of the incumbent's tree that `caique/inquirer` does not import (caique takes no dependency outside the burgee family, U6), so the mock can neither observe nor drive any implementation of ours. Excluded for both sides by exact title (D-20261011-inquirer-prompts-editor-mock). |
| **inquirer-prompts** | `packages/editor/editor.test.ts > editor prompt > goes back to default value on failed validation` | Asserts on, and answers through, `vi.mock('@inquirer/external-editor')`'s `editAsync` — a module of the incumbent's tree that `caique/inquirer` does not import (caique takes no dependency outside the burgee family, U6), so the mock can neither observe nor drive any implementation of ours. Excluded for both sides by exact title (D-20261011-inquirer-prompts-editor-mock). |
| **inquirer-prompts** | `packages/editor/editor.test.ts > editor prompt > surfaces external-editor errors` | Asserts on, and answers through, `vi.mock('@inquirer/external-editor')`'s `editAsync` — a module of the incumbent's tree that `caique/inquirer` does not import (caique takes no dependency outside the burgee family, U6), so the mock can neither observe nor drive any implementation of ours. Excluded for both sides by exact title (D-20261011-inquirer-prompts-editor-mock). |
| **inquirer-prompts** | `packages/editor/editor.test.ts > editor prompt > displays custom waitingMessage` | Asserts on, and answers through, `vi.mock('@inquirer/external-editor')`'s `editAsync` — a module of the incumbent's tree that `caique/inquirer` does not import (caique takes no dependency outside the burgee family, U6), so the mock can neither observe nor drive any implementation of ours. Excluded for both sides by exact title (D-20261011-inquirer-prompts-editor-mock). |
| **inquirer-prompts** | `packages/editor/editor.test.ts > editor prompt > displays custom loadingMessage` | Asserts on, and answers through, `vi.mock('@inquirer/external-editor')`'s `editAsync` — a module of the incumbent's tree that `caique/inquirer` does not import (caique takes no dependency outside the burgee family, U6), so the mock can neither observe nor drive any implementation of ours. Excluded for both sides by exact title (D-20261011-inquirer-prompts-editor-mock). |
| **terminal-link** | `main` | Sets `supportsHyperlinks.stdout = true` on the incumbent's detection module and expects OSC 8 on a headless runner. paratext takes no runtime dependency, so it cannot see an assignment to another package's module object; it answers from the same detection that module computes — graded environment by environment against supports-hyperlinks 4.5.0 in `paratext/src/hyperlinks.test.ts` (A27) — and on that runner the answer is no. The six cases that assign `false` stay graded and pass. |
| **terminal-link** | `stderr` | Sets `supportsHyperlinks.stderr = true` on the incumbent's detection module and expects OSC 8 on a headless runner. paratext takes no runtime dependency, so it cannot see an assignment to another package's module object; it answers from the same detection that module computes — graded environment by environment against supports-hyperlinks 4.5.0 in `paratext/src/hyperlinks.test.ts` (A27) — and on that runner the answer is no. The six cases that assign `false` stay graded and pass. |
| **ink** | `build output files are not nested under build/src/` | `build-output.ts` grades ink's **repository**, not a package: its `before` hook deletes `build/` and runs `npm run build` in the repo root, and its four cases assert the compiled layout (`build/index.js`, no `build/src/`), the `exports` paths of ink's own `package.json`, and the `include` of its `tsconfig.json`. There is no `build` script and no source tree in a vendored suite, so ink 8.0.0 itself fails all four here — and so would any implementation, because none of them is a behaviour of the library. |
| **ink** | `package.json export paths resolve to existing files` | `build-output.ts` grades ink's **repository**, not a package: its `before` hook deletes `build/` and runs `npm run build` in the repo root, and its four cases assert the compiled layout (`build/index.js`, no `build/src/`), the `exports` paths of ink's own `package.json`, and the `include` of its `tsconfig.json`. There is no `build` script and no source tree in a vendored suite, so ink 8.0.0 itself fails all four here — and so would any implementation, because none of them is a behaviour of the library. |
| **ink** | `build/index.js and build/index.d.ts exist` | `build-output.ts` grades ink's **repository**, not a package: its `before` hook deletes `build/` and runs `npm run build` in the repo root, and its four cases assert the compiled layout (`build/index.js`, no `build/src/`), the `exports` paths of ink's own `package.json`, and the `include` of its `tsconfig.json`. There is no `build` script and no source tree in a vendored suite, so ink 8.0.0 itself fails all four here — and so would any implementation, because none of them is a behaviour of the library. |
| **ink** | `tsconfig.json include only contains src` | `build-output.ts` grades ink's **repository**, not a package: its `before` hook deletes `build/` and runs `npm run build` in the repo root, and its four cases assert the compiled layout (`build/index.js`, no `build/src/`), the `exports` paths of ink's own `package.json`, and the `include` of its `tsconfig.json`. There is no `build` script and no source tree in a vendored suite, so ink 8.0.0 itself fails all four here — and so would any implementation, because none of them is a behaviour of the library. |
| **ink** | `Box width constraints only accept numbers` | `style-types.ts` hands ink's own `src/global.d.ts` and `fixtures/box-width-types.tsx` to the TypeScript compiler and asserts no diagnostics. The vendored suite has no source tree and the shim has no types, so ink 8.0.0 itself fails it here (`File 'src/global.d.ts' not found`, `Could not find a declaration file for module '../../shim.js'`). What it checks — `minWidth` and `maxWidth` take numbers only, a string a type error — is held for `controlroom/ink` by `@ts-expect-error` lines in `packages/controlroom/src/ink/types.test.ts`, which the package's own typecheck compiles. |
| **inkjs-ui** | `spinner › spinner` | The case collects every write `ink-testing-library` sees across a spinner's life and expects ink 5's: on unmount ink 5 wrote nothing more in debug mode. ink 8 — the incumbent `controlroom/ink` follows since D-20261006-controlroom-ink-8 — ends a non-interactive debug run with a final `\n` (its own suite pins it: `components.tsx` › `debug mode in CI keeps final newline separation after waitUntilExit`) and then an empty write that resolves the exit only once every queued write has flushed. Measured 2026-10-06: `@inkjs/ui` 2.0.0's suite against real **ink 8.0.0** on React 19.3.0 fails this case with the same diff (`'\n'` and `''` after the last frame) and passes the other 102. The case grades which ink major `@inkjs/ui` is installed over, not the drop-in, so it is excluded on both runs rather than read as 102 here and 103 under ink 5. |
| **ink-6** | `background › Box background with hex color` | The suite raises colour on **its own** chalk singleton (`helpers/force-colors.ts`, `chalk.level = 3` before each case), which ink shares because ink colours through that same module. controlroom/ink colours through roundel, whose level is roundel's policy read from the environment and is nobody's singleton: under the oracle's `FORCE_COLOR=true` it is 1 on a laptop and 3 on GitHub Actions (supports-color's CI table, which roundel's policy reproduces), so the same case passed on one runner and failed on the other. Excluded so both runners publish one number; the drop-in's colour is graded by every other colour case in the suite, at the level the environment gives both implementations (D-20261005-controlroom-ink-drop-in). |
| **ink-6** | `background › Box background with rgb color` | The suite raises colour on **its own** chalk singleton (`helpers/force-colors.ts`, `chalk.level = 3` before each case), which ink shares because ink colours through that same module. controlroom/ink colours through roundel, whose level is roundel's policy read from the environment and is nobody's singleton: under the oracle's `FORCE_COLOR=true` it is 1 on a laptop and 3 on GitHub Actions (supports-color's CI table, which roundel's policy reproduces), so the same case passed on one runner and failed on the other. Excluded so both runners publish one number; the drop-in's colour is graded by every other colour case in the suite, at the level the environment gives both implementations (D-20261005-controlroom-ink-drop-in). |
| **ink-6** | `background › Box background with ansi256 color` | The suite raises colour on **its own** chalk singleton (`helpers/force-colors.ts`, `chalk.level = 3` before each case), which ink shares because ink colours through that same module. controlroom/ink colours through roundel, whose level is roundel's policy read from the environment and is nobody's singleton: under the oracle's `FORCE_COLOR=true` it is 1 on a laptop and 3 on GitHub Actions (supports-color's CI table, which roundel's policy reproduces), so the same case passed on one runner and failed on the other. Excluded so both runners publish one number; the drop-in's colour is graded by every other colour case in the suite, at the level the environment gives both implementations (D-20261005-controlroom-ink-drop-in). |
| **ink-6** | `background › Box background fills with hex color` | The suite raises colour on **its own** chalk singleton (`helpers/force-colors.ts`, `chalk.level = 3` before each case), which ink shares because ink colours through that same module. controlroom/ink colours through roundel, whose level is roundel's policy read from the environment and is nobody's singleton: under the oracle's `FORCE_COLOR=true` it is 1 on a laptop and 3 on GitHub Actions (supports-color's CI table, which roundel's policy reproduces), so the same case passed on one runner and failed on the other. Excluded so both runners publish one number; the drop-in's colour is graded by every other colour case in the suite, at the level the environment gives both implementations (D-20261005-controlroom-ink-drop-in). |
| **ink-6** | `background › Box background fills with rgb color` | The suite raises colour on **its own** chalk singleton (`helpers/force-colors.ts`, `chalk.level = 3` before each case), which ink shares because ink colours through that same module. controlroom/ink colours through roundel, whose level is roundel's policy read from the environment and is nobody's singleton: under the oracle's `FORCE_COLOR=true` it is 1 on a laptop and 3 on GitHub Actions (supports-color's CI table, which roundel's policy reproduces), so the same case passed on one runner and failed on the other. Excluded so both runners publish one number; the drop-in's colour is graded by every other colour case in the suite, at the level the environment gives both implementations (D-20261005-controlroom-ink-drop-in). |
| **ink-6** | `background › Box background fills with ansi256 color` | The suite raises colour on **its own** chalk singleton (`helpers/force-colors.ts`, `chalk.level = 3` before each case), which ink shares because ink colours through that same module. controlroom/ink colours through roundel, whose level is roundel's policy read from the environment and is nobody's singleton: under the oracle's `FORCE_COLOR=true` it is 1 on a laptop and 3 on GitHub Actions (supports-color's CI table, which roundel's policy reproduces), so the same case passed on one runner and failed on the other. Excluded so both runners publish one number; the drop-in's colour is graded by every other colour case in the suite, at the level the environment gives both implementations (D-20261005-controlroom-ink-drop-in). |
| **ink-6** | `background › Box background with hex color - concurrent` | The suite raises colour on **its own** chalk singleton (`helpers/force-colors.ts`, `chalk.level = 3` before each case), which ink shares because ink colours through that same module. controlroom/ink colours through roundel, whose level is roundel's policy read from the environment and is nobody's singleton: under the oracle's `FORCE_COLOR=true` it is 1 on a laptop and 3 on GitHub Actions (supports-color's CI table, which roundel's policy reproduces), so the same case passed on one runner and failed on the other. Excluded so both runners publish one number; the drop-in's colour is graded by every other colour case in the suite, at the level the environment gives both implementations (D-20261005-controlroom-ink-drop-in). |
| **ink-6** | `text › text with ansi256 color` | chalk 5, which ink 6.8 uses, emits `ansi256()` unchanged at level 1 (`\u001B[38;5;194m`); chalk 6, which `roundel/chalk` is graded against, downsamples it to the nearest of the sixteen colours at level 1 (`chalk.js` asserts `new Chalk({level: 1}).ansi256(196)` is `\u001B[91m`). The drop-in colours through roundel, so at level 1 it follows chalk 6. The case passes wherever the level is 2 or more (GitHub Actions) and fails on a laptop at level 1, so it is excluded rather than left to read differently per runner (D-20261005-controlroom-ink-drop-in). |
| **ink-6** | `text › text with ansi256 background color` | chalk 5, which ink 6.8 uses, emits `ansi256()` unchanged at level 1 (`\u001B[38;5;194m`); chalk 6, which `roundel/chalk` is graded against, downsamples it to the nearest of the sixteen colours at level 1 (`chalk.js` asserts `new Chalk({level: 1}).ansi256(196)` is `\u001B[91m`). The drop-in colours through roundel, so at level 1 it follows chalk 6. The case passes wherever the level is 2 or more (GitHub Actions) and fails on a laptop at level 1, so it is excluded rather than left to read differently per runner (D-20261005-controlroom-ink-drop-in). |

### Control failures allowed

The control is the real host run through our harness. Where it fails a case for a reason that
is the harness's and not the host's, the allowance is the exact count, and the gate refuses a
different one — so it can neither hide a regression nor grow quietly.

| Host | Cases | Why |
| :--- | ---: | :--- |
| **yargs** | 2 | Real yargs reports its own version by reading the nearest package.json, and from inside a vendored copy that lookup finds ours. Two usage tests assert the version string; burgee scores 816 where yargs itself scores 814. Documented since the host was activated. |
| **cosmiconfig** | 1 | `index.test.ts` imports `'../src/index.js'` — cosmiconfig's own entry module, by path — in addition to the public entry, and `vi.mock`s `../src/Explorer` and `../src/ExplorerSync` to assert the CONSTRUCTOR ARGUMENTS the entry passes them. The vendor step generates a shim for every internal specifier the suite names, but `../src/index.js` is the host's public entry reached by an internal path, so no shim is written and the file fails to load. That is one graded case, and it fails identically for the control and for the target: it is the harness's file-layout assumption, not a property of either implementation. This is the C4 shape `seniority/spec.md` finding 4 left open, decided here — the fix is in `vendor.ts`'s internal-shim discovery, which is the harness lane's file, and until it lands the honest form is a named allowance of exactly one rather than an unexplained 240. |
| **meow** | 2 | Two cases no implementation can pass from a vendored copy of meow's tests, and they are one assertion made twice: `build › main` and `test › return object` each `t.like` the result against `pkg: {name: 'meow'}`. `pkg` is the nearest package.json, which is the vendored root, and that root is deliberately `@vendored/meow-suite` (`rootPackage()` — upstream's name would let Node's self-reference resolve `meow` to the root rather than the installed package). It carries upstream's `description` and `version`, which the suite also reads; the name is the one field it cannot. Re-measured 2026-09-27: the control is 146 / 148 and `burgee/meow` fails these two and nothing else. The version of this paragraph from 2026-09-21 named `pkg normalization is lazy` as the second and said `build/index.js` was absent; the control passes the first, and the shim serves the second. |
| **signal-exit** | 1 | `signal-exit-test.ts` > `does not exit if user handles signal` fails for signal-exit 4.1.0 itself. Its fixture, `signal-listener.js`, re-sends SIGTERM from a `setTimeout` inside the listener and expects the fourth to kill the process; on current Node the process exits cleanly after the first (`calledListener=1, code=0, signal=null`). Measured 2026-09-23 with the fixture requiring `signal-exit` directly — no shim — on Node 22.22, 24.13 and 26.10 on macOS, and on Node 24 in a Linux container. signal-exit's last release was 2023-07-29, before any of those Nodes. |
| **ink** | 1 | `measure-element.tsx` › `calculate layout while rendering is throttled` fails against ink 8.0.0 itself on darwin, three runs in three (2026-10-06): it renders, re-renders, waits 50 ms and asserts the last write is `Width: 100`, and ink's throttled trailing frame lands after that on this machine — the same program with a 300 ms wait writes `Width: 100`. A timing the case leaves to the machine, not a property of ink. `controlroom/ink` passes it. |
| **yargs-17** | 1 | `helpers > applyExtends > exposes applyExtends helper` extends `./package.json` from the cwd and asserts its `name` is `yargs`. The cwd is the vendored root, whose manifest is deliberately `@vendored/yargs-17-suite` (`rootPackage()` — upstream's name would let Node's self-reference resolve `yargs` to a file that is not here). The current-major row's two allowed failures are the same lookup reading the same file. |

### Cases only some platforms register

The reference is the full suite on every platform, so a case a platform never registers is
counted against us there rather than dropped.

| Host | Cases | Registered | Why |
| :--- | ---: | :--- | :--- |
| **cosmiconfig** | 2 | only on linux | `search-strategies.test.ts` wraps its `global › finds config in OS default directory (XDG)` describe in `if (process.platform === 'linux')`, so its two cases — `async` and `sync` — are **not registered at all** anywhere else. The suite is 241 cases on darwin and 243 on ubuntu, and that is the whole of the difference: no other conditional construct exists in the nine files (`process.platform`, `os.platform`, `describe.each`, `skipIf` and `runIf` return exactly this one hit). The reference is the ubuntu 243, because the reference has to be the full suite or the number means less on the machine that has more. Both pass against cosmiconfig and, since 2026-09-30, against seniority: its global search reads `XDG_CONFIG_HOME` (and `APPDATA` on Windows) as `env-paths` does, through `runtime.ts` (D-20260930-seniority-xdg-config-home). Until then it derived the directory from the home directory alone, failed both, and they were counted against it on every platform rather than excluded — excluding them would have raised the published rate from 76.5% to 77.2% by dropping two cases it lost. They are declared `passing: 2` now for the same reason: a darwin run credits exactly the two it cannot register, and no more. |
| **lilconfig** | 2 | not on win32 | `default for searchFrom till root directory` and `searches root directory correctly`, each wrapped in `if (process.platform !== 'win32')` because both assert an `fs` call list rooted at `/`. They are the only conditional construct in the file — the `isNodeV20orNewer` branches pick an expected *message* and never add or drop a case, and this repository is Node 24 only. So the count does not move between darwin and ubuntu, which is why the reference is 77 on both and no number here changes. It is declared anyway: without it a Windows contributor's control registers 75 of 77 and goes red for doing exactly what the suite told it to, and finding that on their machine is worse than writing it here. |
| **signal-exit** | 8 | only on linux | `all-integration-test.ts` loops twice over `signals` (lines 31 and 64), and the list is the platform's: Linux adds SIGIO, SIGPOLL, SIGPWR and SIGSTKFLT, so the suite registers 135 cases on ubuntu and 127 on darwin — 4 signals × 2 loops. The reference is the ubuntu 135. All 8 pass against signal-exit and against closeout. Windows is not declared because it differs by more than one count can say (the first loop is empty there and the list is three signals long), and the ratchet runs on ubuntu. |

### Directories vendored and not graded

Copied with the suite because its tests need them, and never run as tests themselves — or,
where the reason says so, vendored whole and left out of the grade for what it costs to run.

| Host | Directory | Why |
| :--- | :--- | :--- |
| **yargs** | `fixtures/` | Fixture programs the tests spawn as subprocesses. They match `*.mjs` only because that is how yargs writes an ESM fixture; running one as a test grades nothing. |
| **yargs** | `helpers/` | `utils.mjs`, the output-capture helper the top-level tests import. A helper, never a test — mocha would load it and register no cases. |
| **yargs** | `esm/` | yargs' separate ESM suite, which upstream runs under its own command. Found by this walk on 2026-09-09 and deliberately not graded yet: `platform-shim-test.mjs` imports `lib/platform-shims/esm.mjs`, an internal the vendor step's `../lib/` detector does not reach from a subdirectory, so grading the directory today adds three files that fail to load rather than three that measure anything. Named here so it is a decision with a date rather than a silence; grading it is its own piece of work. |
| **execa** | `fixtures/` | The programs the tests spawn — `noop.js`, `forever.js`, `ipc-echo.js` and a hundred and forty more. Upstream's own glob skips the directory (ava did by convention before 10.1.0); running one as a test grades nothing, and several never exit. |
| **execa** | `helpers/` | Modules the tests import (`fixtures-directory.js`, `stdio.js`, `verbose.js` …). Upstream's own glob skips the directory (ava did by convention before 10.1.0); each one declares no case of its own. |
| **execa** | `convert/` | Vendored and not graded, for cost. execa's suite is 5,125 cases run one file at a time (upstream's own `concurrency: 1`, `--test-concurrency=1` since 10.1.0), and the control measured **647 s** across the twelve directories on 2026-09-27 — past the oracle's 300 s cap on one suite run, and more than half of the ratchet job's 20 minutes on its own. The graded slice is `arguments/`, `methods/` and `return/`: how a command is built, the entry points, and the result and error a caller reads, which is the whole of what bellpull's `run` overlaps with execa (bellpull R1, R6). Nothing is hidden by leaving these out: graded over all 149 files the same day, `bellpull` passed **0** — every file imports `execa`, which bellpull does not export, and fails at link time. Re-measured at 10.1.0 on 2026-10-07 over all 152 files: **0**, for the same reason. D-160. |
| **execa** | `io/` | Vendored and not graded, for cost. execa's suite is 5,125 cases run one file at a time (upstream's own `concurrency: 1`, `--test-concurrency=1` since 10.1.0), and the control measured **647 s** across the twelve directories on 2026-09-27 — past the oracle's 300 s cap on one suite run, and more than half of the ratchet job's 20 minutes on its own. The graded slice is `arguments/`, `methods/` and `return/`: how a command is built, the entry points, and the result and error a caller reads, which is the whole of what bellpull's `run` overlaps with execa (bellpull R1, R6). Nothing is hidden by leaving these out: graded over all 149 files the same day, `bellpull` passed **0** — every file imports `execa`, which bellpull does not export, and fails at link time. Re-measured at 10.1.0 on 2026-10-07 over all 152 files: **0**, for the same reason. D-160. |
| **execa** | `ipc/` | Vendored and not graded, for cost. execa's suite is 5,125 cases run one file at a time (upstream's own `concurrency: 1`, `--test-concurrency=1` since 10.1.0), and the control measured **647 s** across the twelve directories on 2026-09-27 — past the oracle's 300 s cap on one suite run, and more than half of the ratchet job's 20 minutes on its own. The graded slice is `arguments/`, `methods/` and `return/`: how a command is built, the entry points, and the result and error a caller reads, which is the whole of what bellpull's `run` overlaps with execa (bellpull R1, R6). Nothing is hidden by leaving these out: graded over all 149 files the same day, `bellpull` passed **0** — every file imports `execa`, which bellpull does not export, and fails at link time. Re-measured at 10.1.0 on 2026-10-07 over all 152 files: **0**, for the same reason. D-160. |
| **execa** | `pipe/` | Vendored and not graded, for cost. execa's suite is 5,125 cases run one file at a time (upstream's own `concurrency: 1`, `--test-concurrency=1` since 10.1.0), and the control measured **647 s** across the twelve directories on 2026-09-27 — past the oracle's 300 s cap on one suite run, and more than half of the ratchet job's 20 minutes on its own. The graded slice is `arguments/`, `methods/` and `return/`: how a command is built, the entry points, and the result and error a caller reads, which is the whole of what bellpull's `run` overlaps with execa (bellpull R1, R6). Nothing is hidden by leaving these out: graded over all 149 files the same day, `bellpull` passed **0** — every file imports `execa`, which bellpull does not export, and fails at link time. Re-measured at 10.1.0 on 2026-10-07 over all 152 files: **0**, for the same reason. D-160. |
| **execa** | `resolve/` | Vendored and not graded, for cost. execa's suite is 5,125 cases run one file at a time (upstream's own `concurrency: 1`, `--test-concurrency=1` since 10.1.0), and the control measured **647 s** across the twelve directories on 2026-09-27 — past the oracle's 300 s cap on one suite run, and more than half of the ratchet job's 20 minutes on its own. The graded slice is `arguments/`, `methods/` and `return/`: how a command is built, the entry points, and the result and error a caller reads, which is the whole of what bellpull's `run` overlaps with execa (bellpull R1, R6). Nothing is hidden by leaving these out: graded over all 149 files the same day, `bellpull` passed **0** — every file imports `execa`, which bellpull does not export, and fails at link time. Re-measured at 10.1.0 on 2026-10-07 over all 152 files: **0**, for the same reason. D-160. |
| **execa** | `stdio/` | Vendored and not graded, for cost. execa's suite is 5,125 cases run one file at a time (upstream's own `concurrency: 1`, `--test-concurrency=1` since 10.1.0), and the control measured **647 s** across the twelve directories on 2026-09-27 — past the oracle's 300 s cap on one suite run, and more than half of the ratchet job's 20 minutes on its own. The graded slice is `arguments/`, `methods/` and `return/`: how a command is built, the entry points, and the result and error a caller reads, which is the whole of what bellpull's `run` overlaps with execa (bellpull R1, R6). Nothing is hidden by leaving these out: graded over all 149 files the same day, `bellpull` passed **0** — every file imports `execa`, which bellpull does not export, and fails at link time. Re-measured at 10.1.0 on 2026-10-07 over all 152 files: **0**, for the same reason. D-160. |
| **execa** | `terminate/` | Vendored and not graded, for cost. execa's suite is 5,125 cases run one file at a time (upstream's own `concurrency: 1`, `--test-concurrency=1` since 10.1.0), and the control measured **647 s** across the twelve directories on 2026-09-27 — past the oracle's 300 s cap on one suite run, and more than half of the ratchet job's 20 minutes on its own. The graded slice is `arguments/`, `methods/` and `return/`: how a command is built, the entry points, and the result and error a caller reads, which is the whole of what bellpull's `run` overlaps with execa (bellpull R1, R6). Nothing is hidden by leaving these out: graded over all 149 files the same day, `bellpull` passed **0** — every file imports `execa`, which bellpull does not export, and fails at link time. Re-measured at 10.1.0 on 2026-10-07 over all 152 files: **0**, for the same reason. D-160. |
| **execa** | `transform/` | Vendored and not graded, for cost. execa's suite is 5,125 cases run one file at a time (upstream's own `concurrency: 1`, `--test-concurrency=1` since 10.1.0), and the control measured **647 s** across the twelve directories on 2026-09-27 — past the oracle's 300 s cap on one suite run, and more than half of the ratchet job's 20 minutes on its own. The graded slice is `arguments/`, `methods/` and `return/`: how a command is built, the entry points, and the result and error a caller reads, which is the whole of what bellpull's `run` overlaps with execa (bellpull R1, R6). Nothing is hidden by leaving these out: graded over all 149 files the same day, `bellpull` passed **0** — every file imports `execa`, which bellpull does not export, and fails at link time. Re-measured at 10.1.0 on 2026-10-07 over all 152 files: **0**, for the same reason. D-160. |
| **execa** | `verbose/` | Vendored and not graded, for cost. execa's suite is 5,125 cases run one file at a time (upstream's own `concurrency: 1`, `--test-concurrency=1` since 10.1.0), and the control measured **647 s** across the twelve directories on 2026-09-27 — past the oracle's 300 s cap on one suite run, and more than half of the ratchet job's 20 minutes on its own. The graded slice is `arguments/`, `methods/` and `return/`: how a command is built, the entry points, and the result and error a caller reads, which is the whole of what bellpull's `run` overlaps with execa (bellpull R1, R6). Nothing is hidden by leaving these out: graded over all 149 files the same day, `bellpull` passed **0** — every file imports `execa`, which bellpull does not export, and fails at link time. Re-measured at 10.1.0 on 2026-10-07 over all 152 files: **0**, for the same reason. D-160. |
| **meow** | `fixtures/` | Twenty-four CLI programs the tests spawn with execa — two thirds of everything under `test/`. ava's own globs exclude them and the harness's walk did not, so ava was handed them as test files and each one that exits non-zero was counted: the row read `# fail 22` beside `# tests 148 / # pass 144`, a summary that disagrees with itself. Ungraded, `test/` is 12 test files. |
| **signal-exit** | `fixtures/` | Programs the tests spawn as child processes to watch them exit — `exit.js`, `sigint.js`, `sigkill.js` and eighteen more. They match `*.{js,ts}` because that is simply how they are written, and running one as a test grades nothing: it installs a handler and kills itself. Two of them (`signal-capture.js`, `sigkill.js`) reach the implementation through `../../dist/`, which is why `dist/cjs/signals.js` is on the internal-shim list at all. |
| **ink** | `helpers/` | Ten modules the tests import — `render-to-string.ts`, `create-stdout.ts`, `create-stdin.ts`, `test-renderer.ts`, `force-colors.ts`, `act.ts`, `mock-timer-calls.ts`, `reconstruct-terminal.ts`, and `run.ts` and `term.ts`, which spawn a fixture under `node-pty`. Upstream's `npm test` globs `test/*.{ts,tsx}`, one level, so none of them is run as a test; none declares a case. |
| **ink** | `fixtures/` | Sixty TSX programs `run.ts` and `term.ts` spawn in a pseudo-terminal (`node --import=tsx fixtures/<name>.tsx`) for the cases that need a real TTY, and the one `style-types.ts` hands to the TypeScript compiler. Upstream's `npm test` globs `test/*.{ts,tsx}`, one level, so none is run as a test; each renders an app and exits, and grades nothing on its own. |
| **yargs-17** | `helpers/` | `utils.cjs`, the output-capture helper the top-level tests require. A helper, never a test. |
| **ink-6** | `helpers/` | Seven modules the tests import — `render-to-string.ts`, `create-stdout.ts`, `create-stdin.ts`, `test-renderer.ts`, `force-colors.ts`, and `run.ts` and `term.ts`, which spawn a fixture under `node-pty`. Upstream's own `ava.files` excludes the directory (`!test/helpers/**/*`); none of them declares a case. |
| **ink-6** | `fixtures/` | Twenty-eight TSX programs `run.ts` and `term.ts` spawn in a pseudo-terminal (`node --import=tsx fixtures/<name>.tsx`) for the cases that need a real TTY: `exit`, raw mode, `useInput` keystrokes, erase and `<Static>` in a short viewport. Upstream's `ava.files` excludes them (`!test/fixtures/**/*`); each renders an app and exits, and grades nothing on its own. |

### Graded as a ceiling, not a drop-in

The incumbent's own suite, run against a package that deliberately does not implement the
incumbent's API. The rate is the distance between the two, published so it is measured rather
than asserted — it is not a façade on its way to 100%, and `burgee migrate` neither rewrites to
it nor reports it as a path.

| Host | Graded against | Why |
| :--- | :--- | :--- |
| **execa** | `bellpull` | bellpull ships no execa API and will not: `run` resolves a record on a non-zero exit where execa throws, so an execa façade would silently stop every caller's error path firing (bellpull spec R7). The row is graded to publish that distance as a number rather than as a sentence — every graded file imports `execa`, which `bellpull` does not export, and fails at link time. |

## Supported majors

A major is claimed only where the host's **own suite at that major** grades the front-end
level with the host itself — every case the host passes in this harness, passed. The current
major is the release the table above grades. An older major is its own suite, vendored at that
major's last tag and graded in CI beside the current one; the claim is
`SUPPORTED_MAJORS` in `burgee/src/compat.ts`, which `burgee migrate` reads, and a lock holds it
to these rows (C1).

| Host | Majors claimed | Release graded | Older majors graded |
| :-- | :-- | :-- | :-- |
| commander | **14**, **15** | 15.0.0 | **commander-14** (14.0.3) — claimed |
| extra-typings | **15** | 15.0.0 | — |
| yargs | **17**, **18** | 18.2.0 | **yargs-17** (17.7.3) — claimed |
| chalk | **6** | 6.0.1 | — |
| picocolors | **1** | 1.1.1 | — |
| supports-color | **11** | 11.0.0 | — |
| yoctocolors | **2** | 2.2.0 | — |
| ora | **9** | 9.4.1 | — |
| log-update | **8** | 8.0.0 | — |
| boxen | **9** | 9.0.0 | — |
| cli-table3 | **0** | 0.6.5 | — |
| string-width | **8** | 8.3.0 | — |
| strip-ansi | **7** | 7.2.0 | — |
| cross-spawn | **7** | 7.0.6 | — |
| which | **7** | 7.0.0 | — |
| execa | — | — | — |
| rc | **1** | 1.2.8 | — |
| wrap-ansi | **10** | 10.0.2 | — |
| slice-ansi | **9** | 9.0.1 | **slice-ansi-7** (7.1.2) — graded, not claimed |
| cli-truncate | **6** | 6.1.1 | — |
| widest-line | **6** | 6.0.0 | — |
| cosmiconfig | **10** | 10.0.1 | — |
| lilconfig | **3** | 3.1.4 | — |
| dotenv | **18** | 18.0.8 | **dotenv-17** (17.4.2) — graded, not claimed |
| find-up | **8** | 8.0.0 | — |
| clack | **1** | 1.8.1 | — |
| inquirer-prompts | **8** | 8.7.3 | — |
| inquirer-core | **12** | 12.0.4 | — |
| meow | **14** | 14.1.0 | — |
| ansi-escapes | **7** | 7.3.0 | — |
| terminal-link | **5** | 5.0.0 | — |
| term-img | **7** | 7.1.0 | — |
| restore-cursor | **5** | 5.1.0 | — |
| exit-hook | **5** | 5.1.0 | — |
| signal-exit | **4** | 4.1.0 | — |
| onetime | **8** | 8.0.0 | — |
| cli-cursor | **5** | 5.0.0 | — |
| ink | **8** | 8.0.0 | **ink-6** (6.8.0) — graded, not claimed |
| inkjs-ui | — | — | — |

| Host | Front-end | burgee | rate | control | rate | internals (burgee) | internals (control) |
| :--- | :--- | ---: | ---: | ---: | ---: | ---: | ---: |
| **commander-14** | `burgee/commander/v14` | 1331 / 1331 | 100.0% | 1331 / 1331 | 100.0% | 25 / 36 | 36 / 36 |
| **yargs-17** | `burgee/yargs/v17` | 793 / 794 | 99.9% | 793 / 794 | 99.9% | 23 / 23 | 23 / 23 |
| **slice-ansi-7** | `linegauge/slice` | 14 / 15 (1 the host marks failing and we pass) | 93.3% | 15 / 15 | 100.0% | — | — |
| **dotenv-17** | `seniority` | 107 / 141 | 75.9% | 141 / 141 | 100.0% | 0 / 0 | 7 / 13 |
| **ink-6** | `controlroom/ink` | 540 / 584 | 92.5% | 584 / 584 | 100.0% | 0 / 0 | 148 / 148 |

An older major that grades below level is published here and not claimed: a program on it is
left alone by `burgee migrate`, and the note in `hosts.ts` names the cases that differ.

A front-end does not reach 1.0 until its rate is **100%** (C7). Below that it ships pre-1.0
and is never described as compatible. The rate ratchets: a pull request that lowers it fails
CI unless it also lowers the committed baseline, an edit a reviewer sees (C5).

## Other hosts

| Host | Status | Why |
| :--- | :--- | :--- |
| cac | planned | Deferred: 49.4M/wk is almost entirely vite and vitest bundling it, not developers choosing it, so a façade converts few people. |
| citty | planned | Deferred for the same reason as cac: nitro and unjs bundle it. |
| oclif | rejected | Its API is inseparable from its shape: a project layout, a build step and a generator. A façade could not be adopted without adopting the shape that Z1 exists to prevent, and oclif does 10.9M/wk against commander’s 508M, so the shape is also what lost. |

## Reproduce

```bash
npm run compat -- --vendor --control   # vendor both suites, grade the real hosts
npm run compat                          # grade burgee
npm run compat -- --majors --control    # the older majors, against the real hosts (C1)
npm run compat -- --majors              # the older majors, against burgee
```

---

# Agent surfaces

> One declaration projected into every form a caller reads — help, the --json envelope, --schema, an MCP server, completions — and a program that stops and says what to run instead of prompting an agent.

Source: https://burgee.interlace.tools/docs/concepts/agent-surfaces

## What it is

A burgee command is declared once, as data. Every surface a caller reads is projected from
that declaration rather than written beside it:

| Surface | For | What it is |
| :-- | :-- | :-- |
| `--help` | a person | the rendered manifest; `--help --json` is the same as a document. When every command that runs fits in 8 rows, each is listed by its full path with what it takes (`config get <key>`, not `config`). The root help ends with one line for agents naming `--schema`, `--json` and `--explain` |
| `--json` | a script, an agent | one envelope on stdout: `{ ok, data, meta }` or `{ ok: false, error }` |
| `--schema` | an agent, before it calls | the program as data: commands, options, `effects`, the exit-code table, a JSON Schema per command, and one line naming `--explain` for where a value came from |
| `--mcp` | an MCP client | the same commands as MCP tools over stdio |
| `completion <shell>` | a shell | a static script for bash, zsh, fish, pwsh or fig |
| `--explain <option>` | anyone asking "why this value?" | the [configuration](/docs/concepts/configuration) record for one option, on every command that runs and listed in its help |

[Your CLI is an agent tool](/docs/agent-surfaces) has each surface in full: `--schema` and its
character budget, what becomes an MCP tool, how tool arguments map back to flags, the client
configuration, and completions. This page is the model behind them.

## Why it exists

An agent driving a CLI through a shell pays in calls, tokens and misreads: it scrapes help
text, guesses which output line is the result, and waits on a prompt nobody will answer. When
each surface is written by hand beside the command, they drift — the help names a flag the
schema does not, the MCP tool takes an argument the command refuses. Projecting all of them
from one declaration leaves them nothing to drift from.

## The rules

**The envelope is one document on stdout.** Success is
`{"ok":true,"data":<what run returned>,"meta":{"provenance":{…}}}`, with `meta.changed` for an
idempotent command. Failure is `{"ok":false,"error":{"kind","code","message","hint"?,"fix"?,"usage"?}}`,
also on stdout, and stderr carries only `{"error":{"kind","code","message"}}`, one line, for a
caller that reads stderr alone ([Exit codes](/docs/concepts/exit-codes#the-envelope-and-where-errors-go)). `--json` counts only before a `--`. It counts wherever it is
typed before that, including ahead of the command (`demo --json config get user.name`). The
spellings other CLIs use count too: `--format json`, `--format=json`, `--output json` and
`--output=json` are read as `--json`, unless the command declares an option of that name or
one near it. In that case the option is the program's, and a near one makes the reading a
guess, which is refused with a `fix`. [Exit codes and errors](/docs/concepts/exit-codes) has
the failure side.

**A refusal carries its next step.** A failure has a `fix` to run, or, when there is none,
`usage`: the failing command's usage line and options, or the commands that exist for a word the
program does not know, at most 8 rows. An unknown command near a real one gets a `fix` that is
the caller's own line with the word corrected. The agent recovers from the error it already read,
not from a `--help` walk.

**`effects` is required on burgee's own API.** `defineCommand` refuses a runnable command without
`read_only`, `idempotent`, `non_idempotent` or `withheld`. It becomes MCP's `readOnlyHint`,
`idempotentHint` and `destructiveHint`, and `withheld` keeps a command out of `tools/list`. On
`burgee/commander` and `burgee/yargs`, a command that declared nothing is listed as
`effects: 'undeclared'` with no hints (`maps effects to the hints an agent reads, never
defaulting destructive to silence (N6)` in
[`mcp.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/burgee/src/mcp.test.ts)).

**An MCP result is the `--json` envelope, byte for byte.** A tool call runs the command as a
`--json` caller would, so an agent on MCP and one shelling out see one payload (`returns the
--json envelope as the tool result, byte for byte (N4)`).

**An agent is detected, not assumed to be a terminal.** Five variables name one: `AI_AGENT`,
`CLAUDECODE`, `CURSOR_AGENT`, `CODEX_THREAD_ID` and `GEMINI_CLI`. The first one set names
`ctx.agent`. `ctx.interactive` is roundel's `interactive()`, the family's one rule for whether a
person may be asked: a terminal on **stdin**, no `CI`, and none of those five, with `FORCE_TTY=1`
over all three. caique's prompts ask the same function, so a handler and a prompt never disagree
about the same shell (`one rule for whether a person may be asked (N12)` in
[`agent.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/burgee/src/agent.test.ts)).
burgee loads `roundel/terminal` only when it is about to run a handler, so help, `--version`,
`--schema` and `--mcp` never load it. Help's colour is an output decision and still reads stdout
([the output policy](/docs/concepts/output-policy) has both).

A variable joins the five only when it names an agent and nothing else. `CURSOR_TRACE_ID` does
not qualify, because Cursor sets it in every integrated terminal and a person typing there would
never be asked anything.

**Never prompt an agent.** burgee draws no prompt itself. A handler that would ask reads
`ctx.interactive` and, when nobody can answer, calls `ctx.actionRequired({ reason, message, next })`:
the run ends with exit 4 and an envelope carrying `status: "action_required"` and `next[]` —
runnable commands with the program's name in front and the caller's `--json` carried. A prompt
drawn with caique refuses instead of waiting and names the flag to pass (exit 2). Either way the
caller gets a next step, not a hang (`under --json: status, reason, message, runnable next[]
carrying the caller's --json, hint; exit CANCELLED (4)` in `agent.test.ts`).

## Run it

```js title="tool.mjs"
import { defineCommand, defineProgram, run } from 'burgee';

const program = defineProgram({
  name: 'tool',
  commands: [
    defineCommand({
      name: 'deploy',
      description: 'Deploy a build',
      effects: 'non_idempotent',
      examples: [{ command: 'tool deploy --target prod --yes' }],
      output: { cardinality: 'single' },
      options: {
        target: { type: 'string', required: true, description: 'where to deploy' },
        yes: { type: 'boolean', description: 'skip the confirmation' },
      },
      run: (ctx) => {
        if (!ctx.options.yes && !ctx.interactive) {
          ctx.actionRequired({
            reason: 'confirm',
            message: `deploying to ${ctx.options.target} needs confirmation`,
            next: [{ command: `deploy --target ${ctx.options.target} --yes`, when: 'once you have reviewed the plan' }],
          });
        }
        return { target: ctx.options.target, agent: ctx.agent ?? null };
      },
    }),
  ],
});

await run(program);
```

Nobody to confirm, so the program stops and says what to run:

```text title="CLAUDECODE=1 node tool.mjs deploy --target prod --json" exit="4"
{"ok":false,"status":"action_required","reason":"confirm","message":"deploying to prod needs confirmation","next":[{"command":"tool deploy --target prod --yes --json","when":"once you have reviewed the plan"}],"error":{"kind":"cancelled","code":4,"message":"deploying to prod needs confirmation"}}
{"error":{"kind":"cancelled","code":4,"message":"deploying to prod needs confirmation"}}
```

```text title="node tool.mjs deploy --target prod" exit="4"
action required (confirm): deploying to prod needs confirmation
next:
  tool deploy --target prod --yes    once you have reviewed the plan
{"error":{"kind":"cancelled","code":4,"message":"deploying to prod needs confirmation"}}
```

The next command, run by the agent:

```text title="CLAUDECODE=1 node tool.mjs deploy --target prod --yes --json"
{"ok":true,"data":{"target":"prod","agent":"claude-code"},"meta":{"provenance":{"target":{"source":"flag","location":"--target"},"yes":{"source":"flag","location":"--yes"}}}}
```

A run that fails with nothing to fix names what the command takes, in the same envelope:

```text title="CLAUDECODE=1 node tool.mjs deploy --json" exit="2"
{"ok":false,"error":{"kind":"usage","code":2,"message":"missing required option --target","hint":"pass --target <value>","usage":{"command":"tool deploy [options]","options":[{"name":"--target <value>","description":"where to deploy (required)"},{"name":"--yes","description":"skip the confirmation"}]}}}
{"error":{"kind":"usage","code":2,"message":"missing required option --target"}}
```

What an agent reads before it calls, from the same declaration:

```text title="node tool.mjs --schema deploy --field inputSchema"
{"type":"object","properties":{"target":{"type":"string","flag":"--target","description":"where to deploy"},"yes":{"type":"boolean","flag":"--yes","description":"skip the confirmation"}},"required":["target"],"additionalProperties":false}
```

```text title="node tool.mjs --schema deploy --field effects"
"non_idempotent"
```

The same document is a [clispec v0.3](https://clispec.dev) document, so the call to try first and
how much comes back are there too ([the keys](/docs/agent-surfaces#it-is-also-a-clispec-v03-document)):

```text title="node tool.mjs --schema deploy --field example"
{"args":["deploy","--target","prod","--yes"]}
```

```text title="node tool.mjs --schema deploy --field cardinality"
"single"
```

## Where the rules live

- [Your CLI is an agent tool](/docs/agent-surfaces) — every surface in full.
- [Getting started](/docs/getting-started) — `burgee dev`, which serves the program over MCP while
  you write it.
- Specs: [burgee N1–N14](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/intents/burgee/spec.md)
  and [agent-surface-declared](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/intents/agent-surface-declared/spec.md).
- The document `--schema` prints is described by `burgee/program-schema.json`.

---

# Configuration and precedence

> seniority's one fixed order — flag, env, config file, package.json field, default — resolved by a pure function that records where every value came from, so --explain can say what won and what it beat.

Source: https://burgee.interlace.tools/docs/concepts/configuration

## What it is

[seniority](https://seniority.interlace.tools/docs) decides which value an option has when more
than one place sets it. It does three separate things, and keeps them separate:

- **find** a configuration file (`discover`, `search`) — the only part that reads the disk;
- **resolve** each option from the layers it was handed (`resolve`) — a pure function;
- **explain** the result (`explain`, `explanation`) — what won, from where, and what it beat.

burgee uses all three: `envPrefix` and `config: true` on `defineProgram` opt a program into
environment variables and config discovery, and every command gets `--explain <option>`.

## Why it exists

"Where did this value come from?" is the question a user asks when a CLI does something they
did not expect, and an agent asks before it trusts a result. When the order lives in each
program's own code, the answer is different in every tool and written down in none of them.
Here it is data (`ORDER`), the same in every program, and every resolved value carries its
provenance.

## The order

`resolve(specs, layers)` looks at five sources, highest first, and the first one that sets a
value wins:

| Source | Rank | Provenance `location` |
| :-- | ---: | :-- |
| flag | 0 | `--<name>` |
| env | 10 | the variable's name |
| config file | 20 | the file's path, and its line when the loader recorded one |
| `package.json` field | 30 | the `package.json` path |
| default | 40 | none: `{ source: 'default' }` |

A [plugin](/docs/concepts/plugins) can add a source with any integer rank strictly between 0
and 40, so it can sit between env and the config file, but it can never outrank the flag the
user typed or sink below the declared default. A built-in source beats a plugin source at the
same rank. Pinned by `flag > env > config > package.json > default (V1)` in
[`precedence.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/seniority/src/precedence.test.ts)
and by `cannot outrank the flag the user typed` and `cannot sink below the declared default` in
[`plugin.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/seniority/src/plugin.test.ts).

"Sets a value" means anything but `undefined`: `false`, `0` and an empty string are values,
and they win.

## Environment rules

- **Only declared options read the environment.** An option the running command does not
  declare is never looked up (`never reaches an option the running command does not declare
  (yargs #873)`).
- **Names are derived one way.** With a prefix, `dryRun` reads `MYTOOL_DRY_RUN`; an explicit
  `env` on the option wins over the derived name. Without a prefix, no variable is read.
  Nothing maps a variable name back to an option (`names come from the prefix in
  SCREAMING_SNAKE, never camel-cased back (yargs #2005)`).
- **Booleans are strict.** `1`, `true`, `yes` are true and `0`, `false`, `no` are false,
  trimmed and in any case. Anything else is a `ConfigError` (exit code 3 in burgee) that names
  the fix, and `MYTOOL_NO_VERBOSE` is refused with `set MYTOOL_VERBOSE=false instead` rather than
  guessed at.
- **Everything else stays text.** A number from the environment arrives as a string; burgee
  coerces a declared `number` option after resolution.
- **`.env` files are not a layer.** `seniority/dotenv` loads one into an environment and never
  overwrites a variable that is already set unless asked to (`override: true`), so the real
  environment keeps the rank the table gives it.

## Provenance and `--explain`

`resolve` returns `{ values, provenance, candidates }`. `provenance[option]` is the winner's
`{ source, location?, line? }`; `candidates[option]` is every source that was consulted, set or
not. `explain(option, resolution)` renders that record as the text burgee prints for
`--explain <option>`, and the same provenance rides in the `--json` envelope as
`meta.provenance`. A flag's `location` is the flag as it was typed: `--dry-run`, `-n` or
`--no-color`, never the camelCase key (`a flag provenance is the flag the caller typed` in
[`env.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/burgee/src/env.test.ts)). The text and the record are one function (``the human text `explain`
prints IS the record rendered — same function, same bytes`` in
[`explain.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/seniority/src/explain.test.ts)).

## The pure resolve

`resolve` reads nothing: no file, no environment, no `process`. The environment, the parsed
flags and the loaded files are arguments, so the whole precedence table is a unit test with
literals, and a harness can resolve exactly what a program would. Only one file in seniority
names `process`, and a test holds it to that (``names `process` nowhere in its sources, except
the one file that is the program`` in
[`shape.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/seniority/src/shape.test.ts)).

## Finding the file

`discover` tries, in order, and the first file that exists wins:

1. an explicit path (burgee's `--config`), which must exist or it is a `ConfigError`;
2. the path in `<NAME>_CONFIG`;
3. `<name>.config.json`, `.mjs`, `.js` or `.cjs` in the working directory;
4. `<name>/config.json` under `$XDG_CONFIG_HOME`, or `$HOME/.config` when that is unset.

It walks up the directory tree only when the program asks (`upward: true`); by default it does
not, because a surprise config from a parent directory is worse than none (`does not walk
upward by default` in
[`discovery.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/seniority/src/discovery.test.ts)).

## Bounded find-up

When it does walk, `search` stops at the first of: the `stopAt` directory (inclusive), the
filesystem root, a directory it has already seen by real path (so a symlink cycle ends the
walk), or `WALK_LIMIT` — 64 directories, or a smaller `limit`. A pathological depth cannot hang a
start-up (`visits at most WALK_LIMIT directories` and `follows a link once and refuses to follow
a cycle twice` in
[`search.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/seniority/src/search.test.ts)).
It does not stop at a repository root or the home directory by itself; pass `stopAt` for that.

## Run it

```js title="config.mjs"
import { explain, resolve } from 'seniority';

const specs = {
  region: { default: 'us-1' },
  retries: { default: '3' },
  verbose: { type: 'boolean', default: false },
};

const resolution = resolve(specs, {
  flags: { retries: '5' },
  env: { MYTOOL_REGION: 'eu-1', MYTOOL_VERBOSE: 'yes' },
  envPrefix: 'MYTOOL',
  config: { path: './mytool.config.json', data: { region: 'ap-2', retries: '4' }, lines: { region: 2 } },
});

console.log(resolution.values);
console.log(resolution.provenance.region);
console.log(explain('region', resolution));
console.log(explain('retries', resolution));
```

```text title="node config.mjs"
{ region: 'eu-1', retries: '5', verbose: true }
{ source: 'env', location: 'MYTOOL_REGION' }
region = "eu-1"   from env MYTOOL_REGION
         candidates: flag --region (unset), config file ./mytool.config.json:2 "ap-2", default "us-1"

retries = "5"   from flag --retries
         candidates: env MYTOOL_RETRIES (unset), config file ./mytool.config.json "4", default "3"

```

A boolean the environment cannot mean:

```js title="strict.mjs"
import { resolve } from 'seniority';

try {
  resolve({ verbose: { type: 'boolean' } }, { flags: {}, env: { MYTOOL_VERBOSE: 'maybe' }, envPrefix: 'MYTOOL' });
} catch (error) {
  console.log(error.message);
  console.log(`hint: ${error.hint}`);
}
```

```text title="node strict.mjs"
MYTOOL_VERBOSE="maybe" is not a boolean
hint: use MYTOOL_VERBOSE=true or MYTOOL_VERBOSE=false
```

## Where the rules live

- Spec: [seniority R1–R15](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/intents/seniority/spec.md).
- API: [`seniority/precedence`](https://seniority.interlace.tools/docs/api/precedence),
  [`seniority/explain`](https://seniority.interlace.tools/docs/api/explain),
  [`seniority/config`](https://seniority.interlace.tools/docs/api/config),
  [`seniority/find-up`](https://seniority.interlace.tools/docs/api/find-up).
- Guides on seniority's site: [Precedence](https://seniority.interlace.tools/docs/guides/precedence),
  [Environment](https://seniority.interlace.tools/docs/guides/environment) and
  [Config files](https://seniority.interlace.tools/docs/guides/config-files);
  [`--explain` in a CLI](https://seniority.interlace.tools/docs/recipes/explain-flag).
- In burgee: [Your CLI is an agent tool](/docs/agent-surfaces#--explain-option--where-a-value-came-from).

---

# Drop-in façades and migration

> A drop-in reproduces its incumbent's API and behaviour, never its mechanism; burgee migrate moves only the imports the compatibility oracle grades level, and refuses the rest file by file.

Source: https://burgee.interlace.tools/docs/concepts/drop-ins

## What it is

Each family package publishes **drop-ins**: subpaths that export an incumbent's API over the
family's own implementation. `burgee/commander` for `commander`, `roundel/chalk` for `chalk`,
`flagstaff/ora` for `ora`, `linegauge` for `string-width`, and 26 specifiers in all. Moving to
one is an import change and nothing else:

```diff
- import { Command } from 'commander';
+ import { Command } from 'burgee/commander';
```

[`burgee migrate`](/docs/migrate) makes that change across a project, for every drop-in that is
ready.

## Why it exists

A replacement nobody can adopt without a rewrite is not a replacement. A drop-in lets a program
move one import at a time and keep working at every step — and once it has moved, the program
is on the family's mechanisms: one output policy, one exit registry, one width function, and
the [agent surfaces](/docs/concepts/agent-surfaces) that come with burgee's engine.

## The rule: API and behaviour, never mechanism

A drop-in reproduces what the incumbent **does** — its exports, its return values, its exit
codes, its output — because that is what the incumbent's own test suite grades. It does not
reproduce **how** the incumbent does it when a layer of the family owns that job.
`burgee/src/yargs/cliui.ts` is the model the rule cites: a yargs façade that takes `width`,
`strip` and `wrap` from linegauge and keeps only yargs' own layout. The rule is stated, and
enforced, by
[`inline-implementation-lock.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/scripts/inline-implementation-lock.test.ts):
a façade that measures text by hand, reads `NO_COLOR` itself or spawns a process with
`node:child_process` fails it, unless the file is a row in the lock's `KNOWN` table with the
reason — which is how `burgee/commander` keeps commander's own colour rule, because commander's
suite grades exactly that rule.

The façades are also never wrappers: `burgee/commander` is written over burgee's engine, and
no published package depends on commander. The real incumbents are development dependencies of
this repository, installed only to be compared against — by the compatibility oracle and the
benchmarks.

Three more locks hold the surface:

- a drop-in exports every name its incumbent exports, types included, except the gaps listed by
  name
  ([`drop-in-type-surface-lock.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/scripts/drop-in-type-surface-lock.test.ts));
- `require()` of a drop-in returns the same kind of value as `require()` of its incumbent
  ([`drop-in-require-shape-lock.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/scripts/drop-in-require-shape-lock.test.ts));
- the table `burgee migrate` rewrites by is exactly the set of pairs the oracle grades, and the
  table on [Migrate](/docs/migrate) is exactly the one in the code
  ([`migrate-drop-ins-lock.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/scripts/migrate-drop-ins-lock.test.ts)).

## How a drop-in reaches 100%

The [compatibility oracle](/docs/concepts/evidence#the-compatibility-oracle) runs the incumbent's
own test suite against the drop-in. The rate is `passed / reference`, where the reference is
the number of cases the same suite registers against the real incumbent (the *control*), so a
file that fails to load cannot shrink the denominator. Three thresholds use that number:

| Threshold | Condition | What it gates |
| :-- | :-- | :-- |
| **level** | passes at least as many cases as the incumbent passes against itself | whether `burgee migrate` rewrites the import (D-137) |
| **full** | passes every case of the reference | a `yes` in a capability matrix that cites the grade |
| **1.0** | a rate of 100% | the front-end's own 1.0 release; below it, never described as compatible |

A drop-in that is graded but not level — cosmiconfig and dotenv today — is
reported by `migrate` as `partial`, with its grade, and left alone. The rates are on
[Compatibility](/docs/compatibility).

## `burgee migrate`

It rewrites **import specifiers and nothing else**: `import … from`, bare `import`, `export …
from`, `import()` and `require()` with a literal string, and the module a test mocks
(`vi.mock`, `jest.mock`, `vi.importActual`, `jest.requireActual`, `require.resolve` and their
kin). Everything else in a file is left byte for byte. Its safety rules:

- **Only level drop-ins.** The mapping is derived from the graded table, not typed by hand.
- **Only what the project chose.** An incumbent moves when `package.json` declares it, or
  `--only` names it; one imported without being declared is reported as `undeclared`, and
  `--skip` leaves any incumbent alone.
- **Everywhere or nowhere.** An incumbent a refused file or a kept import still names is
  `held` and rewritten in no file, so a program never runs on two copies of one incumbent.
  An import of an error class that another declared dependency still throws is kept for the
  same reason, and that dependency is listed under `transitive`.
- **Only the graded major.** An incumbent installed, or declared, on another major is reported
  under `offMajor` with both versions, and its files are skipped.
- **A file is rewritten whole or not at all.** One refused specifier leaves the whole file as it
  was. The refusals are `deep-import` (`commander/lib/command.js`), `non-literal-specifier`
  (`require(name)`), `unknown-export` (a value import of a name the drop-in does not export) and
  `require-of-default` (a `require()` whose two sides would return different kinds of value), and
  `sibling-state` (a clack file that also imports `@clack/core`, whose settings `caique/clack`
  never reads; it carries a `fix`). A
  type-only import of a missing name is `kept` on the incumbent, not refused.
- **No dirty tree.** Without `--force`, uncommitted changes stop the run before anything is
  written, so the rewrite is one reviewable diff, and the refusal prints its fix: `commit or
  stash your changes, or pass --force`. `--dry-run` writes nothing, so it skips that check.
- **It never edits `package.json`.** It prints the one command that adds the family packages,
  each pinned to the version that carries its graded drop-in, and removes the incumbents that
  are no longer imported, for the package manager the lockfile names. A held incumbent is still
  imported, so it is never called removable or uninstalled (`keeps an incumbent imported only in
  a refused file out of removable, and out of npm uninstall`).
- **It exits 1 when anything was refused**, with the whole report still printed and its first
  line saying the run was `partial`, so an agent can run it unattended and branch on the result.

Each rule is a case in
[`migrate.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/burgee/src/migrate.test.ts):
`refuses a deep import and leaves the file exactly as it was`, `leaves a file entirely unchanged
when one specifier in it is refused`, `leaves an incumbent on another major alone, and says which
versions`, `refuses a dirty tree, and names the fix`, `writes nothing under --dry-run, and still
reports what it would do` and `reports RUNTIME when anything was refused`.

## Run it

A project with two level drop-ins and one deep import, which already depends on roundel:

```json title="package.json"
{ "name": "hello", "dependencies": { "chalk": "^6.0.0", "commander": "^15.0.0", "roundel": "^1.0.0" } }
```

```js title="cli.mjs"
import chalk from 'chalk';
import { Command } from 'commander';

const program = new Command('hello');
program.action(() => console.log(chalk.green('hi')));
program.parse();
```

```js title="legacy.mjs"
import { Help } from 'commander/lib/help.js';

export const help = new Help();
```

```text title="npx burgee migrate --dry-run" exit="1"
partial: 1 file would be rewritten, 1 refused
before the move:
  warn  floor  the family needs Node ^20.19.0 || >=22.13.0; adopting raises this package's floor, a semver-major for it; fix: npm pkg set "engines.node=^20.19.0 || >=22.13.0"
would rewrite:
  chalk -> roundel/chalk  1 import in 1 file
refused, and left exactly as it was:
  legacy.mjs:1  commander/lib/help.js  deep-import
held, rewritten in no file:
  commander  refused in legacy.mjs
graded by the incumbent’s own suite:
  chalk  59 / 59 (the incumbent passes 59)
  commander  1360 / 1360 (the incumbent passes 1360)
declared: commander, chalk
imported: chalk, commander
add: none
removable: chalk
next: npm uninstall chalk
```

`legacy.mjs` is refused and stays as it was, so `commander` is held: `cli.mjs` keeps its
commander import too, and moves only its chalk. `commander` stays installed, and only `chalk`
is removable. roundel is already a dependency, so there is nothing to add; a project without
it would be told `npm install roundel@^` and roundel's current version.

The project declares no `engines.node`, so the report warns, before anything else, that adopting
sets a Node floor it did not have. That is a warning, not a block: a CommonJS package whose
`engines` allowed a Node without `require(esm)` would be blocked and nothing written.
[What it checks before it writes](/docs/migrate#what-it-checks-before-it-writes) lists every check.

## Where the rules live

- [Migrate](/docs/migrate) — the full table of what moves, and every case it leaves alone.
- Spec: [burgee-migrate](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/intents/burgee-migrate/spec.md);
  decision [D-137](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/decisions/D-137.md) (what
  "level" means).
- Each package's **Drop-ins** page and its **Coming from** guides, such as
  [Coming from chalk](https://roundel.interlace.tools/docs/coming-from/chalk).
- [Switching from commander](/docs/vs/commander) and [Switching from yargs](/docs/vs/yargs).

---

# How we prove claims

> Every number the family publishes comes from a file a command produced: incumbent suites graded against a control, baselines that only ratchet, weight bands, capability matrices whose every cell cites its evidence, and the locks that fail when prose outruns the measurement.

Source: https://burgee.interlace.tools/docs/concepts/evidence

## What it is

The family's rule for claims is one sentence in
[`AGENTS.md`](https://github.com/ofri-peretz/burgee/blob/main/AGENTS.md): every number in prose
comes from a file in this repository — a generated page, a baseline, a band — and a claim that
cannot be measured is written as *unmeasured*, not estimated. This page is how that rule is kept:
what produces each number, what stops it drifting, and what a check can and cannot see.

## Why it exists

"Compatible", "lightweight" and "fast" are words every CLI library uses and few measure. A
reader cannot tell a measured claim from a hopeful one, and a claim that was true when written
goes stale the day a dependency moves. So the family publishes numbers, not adjectives, and
makes each one fail a check when the thing it describes changes.

## The compatibility oracle

`packages/compat-oracle` is private and never published. It grades each drop-in with **the
incumbent's own test suite**.

- **Vendored and pinned.** Each suite is copied into `vendor/<host>/`, unmodified apart from the
  import specifier, which a script rewrites to point at a generated shim. A `.source.json` beside
  it records the release, tag, commit and a sha256 per file; a human-readable `PROVENANCE` agrees
  with it field for field (`provenance.test.ts`). Every package a suite needs is pinned exactly,
  because the suite is graded against one release.
- **Control runs.** `--control` runs the same suite against the real incumbent. That proves the
  gate works before it grades anything, and the control's case count is the **reference** every
  rate is divided by — so a file of ours that fails to load cannot shrink the denominator. A
  control is red if it passes nothing, fails more than the allowance declared for that host,
  stops registering cases, or registers more than the reference (`the control verdict` in
  [`gate.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/compat-oracle/src/gate.test.ts)).
- **Baselines that only ratchet.** Each host's grade is committed in `baseline/<host>.json`. A run
  that passes fewer cases than the baseline fails (`the compatibility ratchet` in
  [`run.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/compat-oracle/src/run.test.ts)),
  in `compat.yml`'s `ratchet` job, a required check. Lowering a baseline is a deliberate edit to
  that file, visible in review; no check reads a reason for it.
- **The upstream check.** `compat-upstream.yml` runs daily and opens an issue for each new
  release of an incumbent; `compat-refresh.yml` runs weekly, re-vendors the suites, re-grades, and
  opens a pull request with the diff, never merged automatically.

[Compatibility](/docs/compatibility) is generated from the oracle's run, and `compat:page
--check` in the same required job fails when the published page is not what the results
generate. [Drop-ins](/docs/concepts/drop-ins#how-a-drop-in-reaches-100) has what the rate gates.

## Weight

- **Per subpath.** [Weight, per subpath](/docs/weight) bundles every export of every published
  entry point with `esbuild --bundle --minify --format=esm --platform=node --splitting`, and
  reports the cheapest export, the dearest, and the whole namespace. The same function produces
  the bundle figures on [Benchmarks](/docs/benchmarks).
- **The foundation ceilings.** `.sdlc/bands/foundation-ceilings.json` holds, per layer, the
  installed bytes of the incumbents it replaces *including their dependency trees* — what a user
  removes by switching — and the layer's own size. The band is the only copy of a layer's size;
  each package's `weight.test.ts` fails when the package and the band disagree, and `npm run
  weight:converge` rebuilds, re-measures and rewrites the band and the READMEs that quote it.
- **Tarballs.** `check-published-artifacts.ts` fails when a package's tarball or unpacked size
  grows more than 10% past `.sdlc/bands/artifact-size-baseline.json`
  ([`artifact-size-ratchet-lock.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/scripts/artifact-size-ratchet-lock.test.ts)).
- **Claim ratchets.** A published claim whose measurement sits above its original bar gets a
  ceiling in `.sdlc/bands/claim-ratchets.json` that is gated on every benchmark run and may only
  be lowered: its history is append-only, and a higher entry must cite a newer decision
  ([`claim-ratchets-lock.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/scripts/claim-ratchets-lock.test.ts)).

## Capability matrices

Each package's "Why" page and the [comparison](/docs/comparison) render
`packages/<package>/capabilities.json`: one row per capability, a cell for the package and one per
incumbent it is compared with. [`capabilities-lock.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/scripts/capabilities-lock.test.ts)
reads every cell:

- **Ours.** A `yes` or `partial` names a test file that exists and a substring of a test title in
  it, or a compat baseline — and a `yes` from a baseline only at a full pass.
- **Theirs.** Every incumbent cell names a source: a URL pinned to a release, never a moving
  branch, or a file in the installed or vendored incumbent at the version the oracle grades. A
  local source is read: it must contain what the cell quotes and must not contain what it says
  the incumbent lacks.
- **The columns** are exactly the incumbents the oracle grades for that package.

The lock proves itself with a battery of broken matrices it must refuse (`the lock refuses what it
exists to refuse`): a title the file does not contain, a URL on a moving branch, a grade marked
`yes` that is not a full pass, and more.

## Claim locks

Prose is where a number goes stale, so the places prose quotes a number are locked to its source:

| Lock | Holds |
| :-- | :-- |
| [`dependency-claim-lock`](https://github.com/ofri-peretz/burgee/blob/main/scripts/dependency-claim-lock.test.ts) | a dependency count claimed in a README, a description, a badge or a docs page matches the manifest |
| [`readme-benchmarks-lock`](https://github.com/ofri-peretz/burgee/blob/main/scripts/readme-benchmarks-lock.test.ts) | the benchmark figures in each README are what was measured |
| [`readme-gates-lock`](https://github.com/ofri-peretz/burgee/blob/main/scripts/readme-gates-lock.test.ts) | a quoted bundle figure is what the current build bundles to |
| [`claim-table-lock`](https://github.com/ofri-peretz/burgee/blob/main/scripts/claim-table-lock.test.ts) | the README's claim table cannot claim more than the newest measurement |
| [`pitch-lock`](https://github.com/ofri-peretz/burgee/blob/main/scripts/pitch-lock.test.ts) | the one-line pitch is the same sentence everywhere it appears |
| [`generated-page-gate-lock`](https://github.com/ofri-peretz/burgee/blob/main/scripts/generated-page-gate-lock.test.ts) | every generated page's `--check` runs in a job that reports a required check |

Generated pages — [Compatibility](/docs/compatibility), [Benchmarks](/docs/benchmarks),
[Plugins](/docs/plugins), the graph on [The family and its layers](/docs/concepts/family), each
package's README page and API reference — have a writer and a `--check` twin, and are never edited
by hand. The runnable examples on these concept pages are run by this site's own tests, which
compare what each prints with what the page says it prints.

## Coverage gates

Nine packages declare coverage thresholds of 100% for lines, branches, functions and statements
in their `vitest.config.ts`; linegauge declares 100% except branches at 96.5%, and controlroom,
which has no API, declares none.
[`coverage-config-lock.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/scripts/coverage-config-lock.test.ts)
holds every package to the shared coverage settings, with only `thresholds` added. The thresholds
are evaluated by `npm run coverage`, which runs in the weekly `codecov.yml` workflow and on
demand. The pre-push battery and pull-request CI do not run it, so a pull request that lowers
coverage below a threshold is caught by the next weekly run, not before it merges.

## Run it

A published number, read from the file it comes from. Run it anywhere inside a checkout:

```js title="rates.mjs"
import { existsSync, readFileSync } from 'node:fs';
import { dirname, join } from 'node:path';

let root = process.cwd();
while (!existsSync(join(root, 'packages', 'compat-oracle', 'baseline'))) root = dirname(root);

for (const host of ['commander', 'chalk']) {
  const { passed, reference } = JSON.parse(readFileSync(join(root, 'packages', 'compat-oracle', 'baseline', `${host}.json`), 'utf8'));
  console.log(`${host}: ${passed} / ${reference}`);
}
```

```text title="node rates.mjs"
commander: 1360 / 1360
chalk: 59 / 59
```

The same two numbers are in the table on [Compatibility](/docs/compatibility). If the baseline
moves, this example fails until the page says what the file says.

## Where the rules live

- Specs: [compat-oracle](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/intents/compat-oracle/spec.md),
  [compat-grader-layer](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/intents/compat-grader-layer/intent.md)
  and [upstream-watch](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/intents/upstream-watch/spec.md).
- The research every claim traces to: [Research](/docs/research) and
  [`.sdlc/research/`](https://github.com/ofri-peretz/burgee/tree/main/.sdlc/research).
- Reproducing a grade: the commands at the end of [Compatibility](/docs/compatibility).

---

# Exit codes and errors

> Eight typed exit codes a caller can branch on, one error envelope under --json, and a fixed rule for which stream a failure goes to.

Source: https://burgee.interlace.tools/docs/concepts/exit-codes

## What it is

An exit code is the one thing every caller reads — a shell, a CI runner, an agent — before it
decides what to do next. burgee makes it a contract: eight named codes, each with one meaning,
and nothing else reaches `process.exitCode`.

| Code | Name | Means | The caller should |
| ---: | :-- | :-- | :-- |
| 0 | `OK` | the command completed | carry on |
| 1 | `RUNTIME` | the command ran and failed; never accompanied by help | read the message |
| 2 | `USAGE` | bad arguments, unknown command, missing flag, a prompt with nobody to answer | rewrite the command |
| 3 | `CONFIG` | a config file or the environment could not be loaded or validated | fix the environment |
| 4 | `CANCELLED` | the user or caller cancelled, or the command needs a decision (`actionRequired`) | decide, then run a `next` command |
| 5 | `AUTH` | a credential is missing, expired or refused | log in and run it again |
| 6 | `TIMEOUT` | the deadline `--timeout` set passed | run it again with more time |
| 130 | `SIGINT` | interrupted, after the terminal was restored | stop |

`ExitCode` and `isExitCode()` are exported from `burgee`. `--schema` carries the table as
`exitCodes`, so an agent reads the codes from the program instead of from this page, and root
`--help` prints it under `Exit codes:`, one line per code with what to do about it. The section is
generated from `ExitCode`, so a code appears in help the day it joins the contract (`R4: lists
every ExitCode, by number and name, under "Exit codes:" after the commands` in
[`help-snapshot.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/burgee/src/help-snapshot.test.ts)).

## Why it exists

A CLI that exits 1 for everything tells a caller "something went wrong" and nothing about what
to do. The split above is by *response*: `USAGE` says fix the command, `CONFIG` says fix the
environment, `AUTH` says fix the credential, and none of them needs the message parsed. `AUTH`
is 5 rather than `gh`'s 4 because 4 was already `CANCELLED`, and moving a published code is a
breaking change for everyone who branches on it (the reasoning is in `exit-code.ts`).
`TIMEOUT` is 6 rather than GNU `timeout`'s 124 for the same reason: 124 is inside the 7–125
range `defineError` hands to authors, and 6 was the one number the contract had reserved and
nobody could hold ([D-20261011-timeout-exit-code](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/decisions/D-20261011-timeout-exit-code.md)).
A program run under `timeout 5s` still exits 124, because the wrapper sets it.

**A deadline is the caller's.** Every command takes `--timeout <duration>` (`500ms`, `5s`, `2m`,
or a bare number of milliseconds). When it passes, `ctx.signal` aborts with the timeout as its
reason, the run's `ctx.onExit` handlers run once, and the process leaves with 6 and
`error: timed out after … ms` (`a handler awaiting forever under --timeout 50 exits TIMEOUT, its
cleanup ran once, and ctx.signal aborted` in
[`timeout.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/burgee/src/timeout.test.ts)).

## The rules

**Only the eight.** `isExitCode()` accepts exactly these (`recognises only the eight codes` in
[`exit-code.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/burgee/src/exit-code.test.ts)).
[`exit-code-lock.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/scripts/exit-code-lock.test.ts)
reads them out of `exit-code.ts` and fails on any bare numeric literal passed to an `exit` call
or assigned to `process.exitCode` (`no bare literal reaches an exit outside the two
front-ends`), and on any package's named exit constant that is not one of them (`every exit
constant any package declares is one of the eight`). The two exceptions are the commander and
yargs front-ends, which reproduce their host's own exit codes because the host's suite grades
exactly that.

**A thrown error becomes a code in a fixed order** (`describeFailure` in `failure.ts`):

1. `ctx.exit(code)` with one of the eight leaves silently with that code.
2. `ctx.actionRequired(…)` is 4, with its `next` commands.
3. `UsageError` is 2, `AuthError` is 5, and seniority's `ConfigError` is 3.
4. A class made with `defineError({ name, code })` leaves with its own code.
5. An object whose `code` is the string `'USAGE'`, `'CONFIG'`, `'CANCELLED'` or `'AUTH'` leaves
   with that code. This is how caique's "nobody is there to answer" refusal reaches exit 2 with
   no dependency between caique and burgee.
6. An unknown or malformed option from the parser is 2, with a hint and, where one is close
   enough, the spelling it meant.
7. Anything else — any other `Error`, a rejection, a thrown string — is 1.

**Your own codes.** `defineError({ name, code })` claims a code from 7 to 125 for one class:
below 7 is the contract, and 126 and above mean *not executable*, *not found* and *killed by a
signal* to a shell. A second class claiming a code is refused when it is defined, and a subclass
leaves with its parent's code (`defineError (E7)` in
[`define-error.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/burgee/src/define-error.test.ts)).

**A signal is not an exit code.** On `SIGINT` the program's cleanup runs, the terminal is
restored, and the process dies of the signal, which a shell reports as 130
([Shutdown](/docs/concepts/shutdown) has the mechanism; `dies of the signal rather than exiting,
which is what 130 actually means` in `pty-signal.test.ts`).

## The envelope, and where errors go

| Run | stdout | stderr |
| :-- | :-- | :-- |
| success | the result as text | warnings, such as a deprecation |
| success, `--json` | `{"ok":true,"data":…,"meta":{"provenance":…}}` | warnings |
| a result naming a non-zero `exitCode`, `--json` | `{"ok":false,"data":…,"meta":{"provenance":…}}` | warnings |
| failure | nothing | `error: <message>`, then `hint:` and `fix:` when the error carries them, then `usage:` when there is no `fix`; then, unless stderr is a terminal, `{"error":{"kind":…,"code":…,"message":…}}` |
| failure, `--json` | `{"ok":false,"error":{"kind":…,"code":…,"message":…,"hint"?:…,"fix"?:…,"usage"?:…}}` | `{"error":{"kind":…,"code":…,"message":…}}` |
| needs a decision, `--json` | `{"ok":false,"status":"action_required","reason":…,"message":…,"next":[…],"error":{"kind":"cancelled","code":4,…}}` | `{"error":{"kind":"cancelled","code":4,…}}` |

Under `--json` a failure goes to **stdout**, alone, so a caller that parses stdout gets exactly
one JSON document whether the command succeeded or not; `error.code` is the numeric exit code and
`error.kind` the word for it. `hint` is for a person and `fix` is a command a caller can run.
Pinned by `$name: the envelope is on stdout, alone, and stderr is the one structured line (R6)`
and `puts a usage failure on stdout too, so one rule covers every --json failure` in
[`json-failure.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/burgee/src/json-failure.test.ts).

**Every failure names its kind**, so a consumer branches on a word rather than parsing prose:
`runtime`, `usage`, `config`, `cancelled`, `auth`, `timeout` and `interrupted`, one per code
above, or the kind your own class declares. `--schema` lists them all under `errors`, each with
its exit code and whether a retry may succeed. And **stderr ends with the same failure as one JSON
line** whenever it is not a terminal a person reads: always under `--json`, and after the prose
when stderr is piped or captured. At a terminal nothing changes. That last line is what
[clispec](https://clispec.dev)'s "Structured errors" and cli-agent-lint's SD-1 read, and it
means a caller that only keeps stderr still gets the kind and the code. The examples below are
run with stderr piped, so they show it.

`ok` is the exit code's verdict. A command that finishes and names a non-zero `exitCode` in its
result, like `burgee check` refusing a plugin or `burgee migrate` with refusals, keeps its report
in `data` and says `"ok":false`, because it exits non-zero. Exit 1 there does not mean nothing
happened: `burgee migrate` has rewritten every file it could, and its report's first line, and
its `summary`, says `partial: N files rewritten, M refused`
([Migrate](/docs/migrate#exit-codes) has its codes). Pinned by `says ok: false in its
--json envelope on a refusal, because it exits 1, and still carries the fix` in
[`program.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/burgee/src/program.test.ts).

**A failure says what to do next.** `fix` is one line to run, and it is filled in only when there
is exactly one. It is always the caller's own command line, from the program name, with one thing
corrected: an unknown option replaced by the flag it was nearest to (`--nmae=ada` becomes
`--name=ada`), an unknown command's word replaced by the command it was nearest to, or, when the
word was really an argument, the one command below that takes it inserted before it (`config
user.name` becomes `config get user.name`). A word typed with dashes where a command goes is
matched by its name, so `--get` is `config get`. A fix is never run for you. The one exception is
a request for JSON in another CLI's spelling or position (`--format json`, or `--json` ahead of
the command), which is not a refusal at all: the command runs with `--json`
([Agent surfaces](/docs/concepts/agent-surfaces#the-rules)). When there is none and the code is `USAGE` or `RUNTIME`, the
failure carries `usage` instead. That is the failing command's usage line from the program name,
then its visible options with the notes help prints: required, default, choices, relations and
env. An unknown command carries the commands that exist and points at `--schema`, and at
`--explain` for where a value came from. Either list is
at most 8 rows, and `more` names the `--help` that has the rest. It is a reminder, not a help
screen: no description, no examples, no global options, and the exit code is the one the table
above gives. `AUTH`, `CONFIG` and your own codes carry no `usage`, because their remedy is not an
option. In the envelope it is
`"usage":{"command":"deploy push [options]","options":[{"name":"--target <value>","description":"where to push (required)"}]}`,
with `commands` in place of `options` for an unknown command. Pinned by
[`failure-teaches.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/burgee/src/failure-teaches.test.ts).

On `burgee/commander` and `burgee/yargs`, `error.code` is a string (`'usage'`, `'auth'`,
`'runtime'`), and a parse error keeps the host's own code, such as `commander.unknownOption`:
the front-ends reproduce their host, and add neither `kind` nor the stderr line.

Your own class's kind is its name in snake case, less a trailing `Error` (`QuotaError` is
`quota`), or the one it declares: `defineError({ name: 'QuotaError', code: 7, kind: 'quota',
retryable: false, description: 'the target is out of quota' })`. A declared kind is snake_case
and one class's alone, or `defineError` throws. A kind someone already holds, such as a class
named `TimeoutError` beside the contract's `timeout`, is told apart by its code (`timeout_12`).

## Run it

```js title="deploy.mjs"
import { AuthError, defineCommand, defineError, defineProgram, run } from 'burgee';

const QuotaError = defineError({ name: 'QuotaError', code: 7 });

const program = defineProgram({
  name: 'deploy',
  commands: [
    defineCommand({
      name: 'push',
      description: 'Push a build',
      effects: 'non_idempotent',
      options: {
        target: { type: 'string', required: true, description: 'where to push' },
        token: { type: 'string', description: 'an access token' },
      },
      run: ({ options }) => {
        if (options.token === undefined) throw new AuthError('no access token', 'pass --token', 'run `deploy login` first');
        if (options.target === 'moon') throw new QuotaError('the moon is out of quota', { hint: 'try --target mars' });
        return { target: options.target, pushed: true };
      },
    }),
  ],
});

await run(program);
```

```text title="node deploy.mjs push --target prod --token t --json"
{"ok":true,"data":{"target":"prod","pushed":true},"meta":{"provenance":{"target":{"source":"flag","location":"--target"},"token":{"source":"flag","location":"--token"}}}}
```

A missing credential is 5, as prose on stderr or as the envelope on stdout:

```text title="node deploy.mjs push --target prod" exit="5"
error: no access token
hint: pass --token
fix: run `deploy login` first
{"error":{"kind":"auth","code":5,"message":"no access token"}}
```

```text title="node deploy.mjs push --target prod --json" exit="5"
{"ok":false,"error":{"kind":"auth","code":5,"message":"no access token","hint":"pass --token","fix":"run `deploy login` first"}}
{"error":{"kind":"auth","code":5,"message":"no access token"}}
```

A missing option and a mistyped command are both 2. With no `fix` to run, the missing option
carries what `push` takes:

```text title="node deploy.mjs push --token t --json" exit="2"
{"ok":false,"error":{"kind":"usage","code":2,"message":"missing required option --target","hint":"pass --target <value>","usage":{"command":"deploy push [options]","options":[{"name":"--target <value>","description":"where to push (required)"},{"name":"--token <value>","description":"an access token"}]}}}
{"error":{"kind":"usage","code":2,"message":"missing required option --target"}}
```

A mistyped command is corrected, and the fix is the caller's own line with the word replaced:

```text title="node deploy.mjs psuh --target prod" exit="2"
error: unknown command "psuh"
hint: did you mean push?
fix: deploy push --target prod
{"error":{"kind":"usage","code":2,"message":"unknown command \"psuh\""}}
```

An author's own class leaves with its own code:

```text title="node deploy.mjs push --target moon --token t --json" exit="7"
{"ok":false,"error":{"kind":"quota","code":7,"message":"the moon is out of quota","hint":"try --target mars"}}
{"error":{"kind":"quota","code":7,"message":"the moon is out of quota"}}
```

## Where the rules live

- Spec: [burgee E1–E7](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/intents/burgee/spec.md).
- [Your CLI is an agent tool](/docs/agent-surfaces) — the `action_required` envelope and
  `next[]`.
- [The floor](/docs/the-floor) — the requirements every CLI on burgee meets.

---

# The family and its layers

> One job per package: six leaves that depend on nothing, three packages that compose them, dependencies that point one way, nothing installed from outside the family, and the locks that hold each rule.

Source: https://burgee.interlace.tools/docs/concepts/family

## What it is

burgee is one package of ten published from this repository. Each owns one job, and has a
drop-in path for the packages that do that job today; the [package map](/docs/packages) lists
them. They
split into three layers:

- **Six leaves** depend on nothing: `bellpull` (subprocesses), `closeout` (exit handlers and
  terminal restore), `linegauge` (text width), `paratext` (terminal escapes beyond colour),
  `roundel` (colour and the [output policy](/docs/concepts/output-policy)) and `seniority`
  (configuration).
- **Three compose them**: `burgee` (the CLI framework), `flagstaff` (rendering) and `caique`
  (prompts).
- **One composes those**: `controlroom` (screens), which lays out flagstaff's components and
  reads keys through caique.

## Why it exists

A program can adopt one layer without the others: a CLI that only needs text measured
installs `linegauge` and nothing else. That is only true while the split is real. The
moment `burgee` measures a string's width itself, or reaches for `chalk` instead of
`roundel`, the layers become a directory layout. The rules below are what keep it real, and
each one is a test rather than a convention.

## The graph

{/* layers:start */}

![The family's dependency graph: burgee depends on bellpull, closeout, linegauge, roundel, seniority; caique depends on bellpull, closeout, linegauge, paratext, roundel; controlroom depends on caique, closeout, flagstaff, linegauge, paratext, roundel; flagstaff depends on closeout, linegauge, paratext, roundel. The 6 leaves depend on nothing.](/concepts/family-layers.svg)

4 packages compose, 6 are leaves: 20 dependency edges inside the family, every one pointing down at least one layer, and none outside it. Generated by `npm run layers:page` from each public package's `package.json`; do not edit by hand.

| Package | Layer | Depends on | Used by | Outside the family |
| :--- | :--- | :--- | :--- | :--- |
| `burgee` | composes | `bellpull`, `closeout`, `linegauge`, `roundel`, `seniority` | — | nothing |
| `caique` | composes | `bellpull`, `closeout`, `linegauge`, `paratext`, `roundel` | `controlroom` | nothing |
| `controlroom` | composes | `caique`, `closeout`, `flagstaff`, `linegauge`, `paratext`, `roundel` | — | react (optional peer), react-reconciler (optional peer) |
| `flagstaff` | composes | `closeout`, `linegauge`, `paratext`, `roundel` | `controlroom` | nothing |
| `bellpull` | leaf | nothing | `burgee`, `caique` | nothing |
| `closeout` | leaf | nothing | `burgee`, `caique`, `controlroom`, `flagstaff` | nothing |
| `linegauge` | leaf | nothing | `burgee`, `caique`, `controlroom`, `flagstaff` | nothing |
| `paratext` | leaf | nothing | `caique`, `controlroom`, `flagstaff` | nothing |
| `roundel` | leaf | nothing | `burgee`, `caique`, `controlroom`, `flagstaff` | nothing |
| `seniority` | leaf | nothing | `burgee` | nothing |

{/* layers:end */}

## The rules

**1. Nothing from outside the family.** A published package's `dependencies`,
`peerDependencies` and `optionalDependencies` name only packages published from this
repository. What a caller installs comes from one repository and one supply chain.
Pinned by `installs nothing from outside this repository — dependencies, peers or optional
(D-111)` in [`package-shape-lock.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/scripts/package-shape-lock.test.ts),
by `holds zero external runtime dependencies across the family` in
[`layer-boundaries-lock.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/scripts/layer-boundaries-lock.test.ts),
and, against a real install of each package on its own, by `installs nothing but itself and
the in-family packages it declares` in
[`independence-install-lock.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/scripts/independence-install-lock.test.ts).
A README, a description or a docs page that claims a dependency count the manifest
contradicts fails
[`dependency-claim-lock.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/scripts/dependency-claim-lock.test.ts).

**2. Dependencies point one way.** `package-shape-lock` reads the family bottom-up —
`linegauge`, `seniority`, `bellpull`, `closeout`, `paratext`, `roundel`, `flagstaff`,
`caique`, `controlroom`, `burgee` — and a package may depend only on one earlier in that
order: `has no external runtime dependencies, and same-repo ones only point up the family
(K1, U1, U6)`. All six leaves are its foundation tier, graded by `%s depends on nothing:
it is the floor`.

**3. Never leaf to leaf.** A leaf that depended on another leaf would stop being a leaf, and
every package that uses it would sit a third tier up. `package-shape-lock` states it outright:
`%s has no edge to a sibling, in any dependency field` checks every leaf's `dependencies`,
`devDependencies`, `peerDependencies` and `optionalDependencies` against every workspace in the
repo, and `fails when %s gains a sibling dependency` shows the check going red. The generator of
the graph above refuses it too: every edge must end at a package that depends on nothing in the
family, and `npm run layers:page -- --check` runs in the `fast` job the required Quality Gate
reads.
paratext is the case that shows the cost: it is a leaf, so its hyperlink detection keeps a
declared fork of supports-color rather than importing roundel.

**4. No package depends on an incumbent a sibling layer covers.** The list of what each layer
covers is `LAYERS` in
[`compat-oracle/src/demand.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/compat-oracle/src/demand.ts),
and that list *is* the definition of each layer's job: needing `string-width` is the same
thing as needing `linegauge`. `layer-boundaries-lock` derives the rule from it — `%s depends
on no incumbent another layer replaces` — so the job table is written once.

**5. A sibling owns each mechanism.** A dependency is the easy half to check. The expensive
half is writing a sibling's code by hand, which leaves no dependency behind.
[`inline-implementation-lock.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/scripts/inline-implementation-lock.test.ts)
scans every package's source for 17 shapes that can only be a layer's job, and fails when a
file outside the owner has one:

| Owner | Mechanisms it owns |
| :-- | :-- |
| `bellpull` | spawning a subprocess; resolving an executable across platforms; looking a command up on `PATH` |
| `closeout` | registering a signal handler; hiding or showing the cursor; switching raw mode; hooking process exit |
| `roundel` | reading a colour variable (`NO_COLOR`, `FORCE_COLOR`, `COLORTERM`, `CLICOLOR`); deciding whether this is CI |
| `seniority` | walking up the directory tree; naming a `.env` file |
| `caique` | decoding keypresses |
| `flagstaff` | carrying spinner frames |
| `linegauge` | matching ANSI escapes with a regex; counting painted rows by their newlines; measuring, wrapping or stripping text by hand |
| `paratext`, `linegauge`, `roundel`, `closeout` | spelling a CSI or OSC sequence |

A drop-in façade may reproduce an incumbent's API and behaviour; it may not reimplement the
mechanism a layer owns ([Drop-ins](/docs/concepts/drop-ins) has the rule). The files that
still do are rows in the lock's `KNOWN` table, each with its reason, and the table may only
shrink: `only goes down` and `keeps the list honest — an entry that no longer offends must be
removed`. The lock says plainly what it cannot see: measuring display text with `.length`
looks like any other `.length`, and still needs a reader.

**6. Every layer is used.** A layer nothing else uses has never been proven to fit the stack.
[`composition-lock.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/scripts/composition-lock.test.ts)
reads the band
[`.sdlc/bands/composition.json`](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/bands/composition.json):
the count of edges inside the family may only go up (`has at least as many edges as the last
time this was recorded`), and every package but burgee is used by another or is listed as
`awaiting` one with a reason (`%s is used by another package, or is declared as awaiting
one`). A package that gains a consumer must leave that list. Today `flagstaff`, `caique` and
`controlroom` are awaiting: burgee renders no spinner, box or table, and draws no prompt, so
an edge to either would be manufactured.

## Run it

Each leaf installs and loads on its own. This file imports two leaves and nothing that
composes them:

```js title="leaves.mjs"
import { width } from 'linegauge';
import { colorLevel } from 'roundel/policy';

console.log(width('古池や'), width('\u001B[31mred\u001B[39m'));
console.log(colorLevel({ env: { FORCE_COLOR: '2' }, isTTY: { stdout: false } }));
```

```text title="node leaves.mjs"
6 3
2
```

## Where the rules live

- Spec: [cli-output-stack U1 and U6](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/intents/cli-output-stack/spec.md)
  (nothing from outside the family, and the tier order); decisions
  [D-111](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/decisions/D-111.md) (nothing
  from outside, peers included), [D-180](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/decisions/D-180.md)
  (the mechanism table) and [D-181](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/decisions/D-181.md)
  (roundel owns colour and interactivity).
- [CONTRIBUTING.md](https://github.com/ofri-peretz/burgee/blob/main/CONTRIBUTING.md) — what
  the checks hold a change to.
- [Weight, per subpath](/docs/weight) — what each entry point of each layer costs.

---

# Concepts

> How the burgee family works, on its own terms: the ideas every package shares, the exact rules behind them, and the tests that hold each rule.

Source: https://burgee.interlace.tools/docs/concepts

The package sites say how to use each package, and the comparison pages say how it differs from
the packages it has drop-in paths for. These pages say how the family itself works: the ideas the ten packages share,
why each exists, the rule as the code applies it, and the test that fails if the rule stops
being true. Each has an example this site's tests run.

## The shape of the family

- [The family and its layers](/docs/concepts/family) — one job per package, six leaves and three
  packages that compose them, dependencies that point one way, and nothing installed from outside.
- [Drop-in façades and migration](/docs/concepts/drop-ins) — reproduce an incumbent's API and
  behaviour, never its mechanism; how `burgee migrate` decides what it may move.
- [The plugin system](/docs/concepts/plugins) — one plain object, one published schema, one set
  of refusal codes, and a `check` command in every package.

## What every run decides

- [The output policy](/docs/concepts/output-policy) — which mode a run is in, how much colour it
  may use, and whether anybody is there to type.
- [The static projection](/docs/concepts/static-projection) — the plain-text form every live
  widget and terminal capability must have.
- [Agent surfaces](/docs/concepts/agent-surfaces) — one declaration projected into `--json`,
  `--schema`, `--mcp` and completions, and a program that never prompts an agent.
- [Exit codes and errors](/docs/concepts/exit-codes) — eight typed codes, one error envelope, and
  which stream a failure goes to.
- [Configuration and precedence](/docs/concepts/configuration) — one fixed order, a pure resolve,
  and provenance for every value.
- [Shutdown and terminal restore](/docs/concepts/shutdown) — one registry for every way a process
  leaves, a deadline, and the terminal restored last.
- [Width and text correctness](/docs/concepts/text-width) — how many columns a string occupies,
  counted by grapheme cluster and East Asian Width.

## How the claims are kept

- [How we prove claims](/docs/concepts/evidence) — incumbent suites graded against a control,
  baselines that only ratchet, weight bands, capability matrices with evidence in every cell, and
  the locks that fail when prose outruns a measurement.

---

# The output policy

> One function decides where output is going and how much colour it may carry: roundel/policy's outputMode() and colorLevel(), and roundel/terminal's interactive(). The packages that draw ask them rather than reading the process themselves.

Source: https://burgee.interlace.tools/docs/concepts/output-policy

## What it is

Two subpaths of [roundel](https://roundel.interlace.tools/docs) answer the questions every
package that draws has to ask before it writes a byte:

- [`roundel/policy`](https://roundel.interlace.tools/docs/api/policy): **which mode** this run
  is in (`outputMode`), and **how much colour** it may use (`colorLevel`).
- [`roundel/terminal`](https://roundel.interlace.tools/docs/api/terminal): **is anybody there
  to type** (`interactive`), and can the terminal draw a tick (`unicode`).

All four are pure functions of a runtime you pass in (`env`, `isTTY`, and for colour `argv`),
never of `process`. The same input always gives the same answer, so a test passes a literal
and a harness can ask the question a program asked.

## Why it exists

A spinner, a prompt and the help text each have to decide whether the terminal is a
terminal. When each package decides its own way, they disagree about the same run: one
animates into a CI log while another has already gone plain. `roundel/policy`'s own
documentation cites that failure (clack #286) as the reason it exists: every package in the
family that draws asks here instead of reading `isTTY`, `NO_COLOR`, `FORCE_COLOR`, `CI`,
`CLI_ACCESSIBLE` or a `--color` flag itself.

The exceptions are named, not tolerated: `flagstaff/ora`'s `isInteractive`, `caique/clack`'s
`isCI`, `burgee/commander`'s colour check and paratext's hyperlink detection each reproduce
their incumbent's own detection, because the incumbent's suite grades exactly that. Each is a
row, with its reason, in the `KNOWN` table of
[`inline-implementation-lock.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/scripts/inline-implementation-lock.test.ts).

## The modes

`outputMode(rt, { json })` returns one of five modes. The first row that matches wins:

| Order | Mode | Chosen when |
| ---: | :-- | :-- |
| 1 | `json` | the caller passed `{ json: true }`: the run was asked for `--json` |
| 2 | `accessible` | `CLI_ACCESSIBLE` is set, terminal or not |
| 3 | `tty` | stdout is a terminal |
| 4 | `ci` | `CI` is set and stdout is not a terminal |
| 5 | `pipe` | anything else |

An empty variable is not set: `CI=` and `CLI_ACCESSIBLE=` are the same as leaving them out,
the convention `NO_COLOR` established. `--json` is passed in rather than read from `argv`,
because whether a run asked for structured output is the argument parser's knowledge.

There is no `agent` mode. An agent reading a pipe is `pipe`, an agent that asked for
`--json` is `json`, and whether an agent can be *asked* something is a separate question,
`interactive()`, below.

Pinned by `outputMode — R1, first match wins` and `an empty variable is not set` in
[`policy.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/roundel/src/policy.test.ts).

## The mode is not the colour

The mode decides **redraws**: whether a component animates in place (`tty`) or prints its
[static projection](/docs/concepts/static-projection) once per change. It never decides the
colour level, which `colorLevel(rt, { json })` answers from the user's instruction first and
detection second, in this order:

1. **`--json`, `NO_COLOR`, or accessible with nothing asked → 0.** Structured output carries no
   escapes. A non-empty `NO_COLOR` beats every instruction below, including `FORCE_COLOR=3`
   and `--color`. `CLI_ACCESSIBLE` defaults to 0, because colour is noise to a screen reader,
   but an explicit ask still wins over it.
2. **An exact instruction → that level.** `FORCE_COLOR=0` (or `false`) is read *before* any
   flag, so `FORCE_COLOR=0 --color=256` is off: an explicit "off" is never undone by a level
   flag. After that the `--color` flags in `argv` outrank a numeric `FORCE_COLOR`:
   `--no-color`, `--no-colors`, `--color=false|never` are 0; `--color=256` is 2;
   `--color=16m|full|truecolor` is 3. A numeric `FORCE_COLOR` is that level, clamped to 3.
   Only flags before a `--` terminator count, and an unrecognised value (`--color=lots`) is no
   instruction.
3. **Azure Pipelines** (`TF_BUILD` and `AGENT_NAME`) → 1, the one runner read above the pipe
   check.
4. **A pipe nobody asked to colour → 0.**
5. **`TERM=dumb`** → the floor: 1 if something asked for colour (`FORCE_COLOR=true`,
   `--color`), else 0.
6. **Detection.** With `CI` present, the CI vendor's level (`GITHUB_ACTIONS`, `GITEA_ACTIONS`,
   `CIRCLECI` are 3; `TRAVIS`, `APPVEYOR`, `GITLAB_CI`, `BUILDKITE`, `DRONE` and Codeship are
   1; any other runner 0); otherwise `COLORTERM=truecolor` is 3, a `TERM` ending in `-256` or
   `-256color` is 2, and a known `TERM` or any `COLORTERM` is 1. An ask for colour without a
   level (`FORCE_COLOR=true`, `--color`) never goes below 1.

The levels are chalk's: 0 none, 1 sixteen colours, 2 256 colours, 3 truecolor. With no
instruction the order is supports-color's, which chalk's own `level.js` asserts, so the
family and chalk agree about a bare pipe. Each rule is a `describe` block in
[`policy.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/roundel/src/policy.test.ts):
`R2 revised 2026-09-08: FORCE_COLOR is the user’s instruction, in any mode`,
`the --color flags, when the caller hands over argv`,
`an explicit “colour off” is never overridden into colour on`,
`accessible mode is a pipe, not a terminal (R2)` and
`the CI vendor table, once the run has asked for colour`.
[Colour levels](https://roundel.interlace.tools/docs/guides/colour-levels) on roundel's site
has the full table.

## Is anybody there to type?

`interactive(rt)` is true when `FORCE_TTY=1`, and otherwise only with a terminal on stdin,
no non-empty `CI`, and none of the agent variables `AI_AGENT`, `CLAUDECODE`, `CURSOR_AGENT`,
`CODEX_THREAD_ID`, `GEMINI_CLI` (exported as `AGENTS`). An agent may have a terminal; what it
does not have is a person. Pinned by the `interactive` block of
[`terminal.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/roundel/src/terminal.test.ts),
including `names CLAUDECODE, which is the case that hung an agent`.

Those five are the whole list, and a variable joins it only when it **uniquely** identifies an
agent: the agent sets it, and no terminal a person types in does. `CURSOR_TRACE_ID` fails that
test, because Cursor sets it in every integrated terminal, and taking it would stop every person
in Cursor from being asked anything (`asks a person in Cursor` in the same file).

## Run it

`colorLevel` and `outputMode` read a runtime; this one describes the real process:

```js title="policy.mjs"
import { colorLevel, outputMode } from 'roundel/policy';
import { interactive } from 'roundel/terminal';

const json = process.argv.includes('--json');
const rt = {
  env: process.env,
  argv: process.argv.slice(2),
  isTTY: { stdout: process.stdout.isTTY === true, stdin: process.stdin.isTTY === true },
};

console.log(`mode=${outputMode(rt, { json })} level=${colorLevel(rt, { json })} interactive=${interactive(rt)}`);
```

Piped, as every command below runs, with stdin closed:

```text title="node policy.mjs"
mode=pipe level=0 interactive=false
```

```text title="CI=1 node policy.mjs"
mode=ci level=0 interactive=false
```

```text title="CLI_ACCESSIBLE=1 node policy.mjs --color=256"
mode=accessible level=2 interactive=false
```

```text title="NO_COLOR=1 FORCE_COLOR=3 node policy.mjs --color=256"
mode=pipe level=0 interactive=false
```

```text title="FORCE_COLOR=0 node policy.mjs --color=256"
mode=pipe level=0 interactive=false
```

```text title="CI=1 GITHUB_ACTIONS=true FORCE_COLOR=true node policy.mjs"
mode=ci level=3 interactive=false
```

```text title="FORCE_COLOR=1 node policy.mjs --json"
mode=json level=0 interactive=false
```

```text title="FORCE_TTY=1 node policy.mjs"
mode=pipe level=0 interactive=true
```

## How the family consults it

Only packages that compose may import roundel ([the family](/docs/concepts/family) has the
rule), so the policy is read by the three packages that draw, and by nothing below them:

| Package | Asks | For |
| :-- | :-- | :-- |
| [flagstaff](https://flagstaff.interlace.tools/docs/guides/static-projection) | `outputMode` | once per `hoist()`: `tty` animates, `json` writes NDJSON to stderr, every other mode prints the static projection; a runtime that says `quiet` draws nothing |
| flagstaff | `unicode` | `flagstaff/ora`'s symbols, as is-unicode-supported decides them |
| [caique](https://caique.interlace.tools/docs/guides/never-hangs) | `interactive` | `caique/decide`: nobody there means refuse and name the flag, never wait |
| caique | `unicode` | `caique/inquirer`'s glyphs |
| burgee | `interactive` | `ctx.interactive`, whether a handler may ask: loaded only on the path that runs one |
| burgee | `colorLevel` | whether help is coloured (`help.ts`'s `colorFor`) |

Every question-side decision in the family is `interactive()`. burgee's `ctx.interactive` is
roundel's answer, not a rule of its own: before 2026-09-30 it came from `detectAgent`, which read
stdout and ignored `CI`, so a CI job with a pseudo-terminal was "ask" to a burgee handler and
"refuse" to a caique prompt (D-20260930-one-interactive-rule). burgee imports `roundel/terminal`
in a chunk of its own, on the path that hands a handler its context, so its root entry, which
denies roundel by name, reaches none of it. Output-side decisions stay on the output policy: help
colours by `colorLevel` over stdout, and `ctx.agent` still names the agent. Pinned by
`one rule for whether a person may be asked (N12)` in
[`agent.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/burgee/src/agent.test.ts).

**The caller's flags reach the policy through `ctx.runtime`.** Every burgee command takes
`--no-color`, `--color=always|never|auto` and `-q`/`--quiet` (a command that declares an option
of the same name keeps it). The engine hands each handler `ctx.runtime`: the environment,
whether stdout is a terminal, the colour flag as `colorLevel` reads it, and `quiet`. Spread it
into what you pass flagstaff's `hoist()` and the spinner is uncoloured under `--no-color` and
draws nothing at all under `--quiet`; stdout's data, the `--json` envelope and every failure
still print. Pinned by `--no-color under FORCE_COLOR=3 prints no SGR: in help, and in what the
handler is told` in
[`color.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/burgee/src/color.test.ts)
and `stdout and the --json envelope are byte-identical with and without it, and stderr is empty`
in [`quiet.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/burgee/src/quiet.test.ts).

The leaves take a runtime slice of the same shape and decide their own narrower question
from it: paratext whether a terminal escape is supported, for instance. They cannot import
roundel, because a leaf depends on nothing in the family.

## Where the rules live

- Spec: [roundel R1, R2 and R12](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/intents/roundel/spec.md).
- API: [`roundel/policy`](https://roundel.interlace.tools/docs/api/policy),
  [`roundel/terminal`](https://roundel.interlace.tools/docs/api/terminal).
- Guides: [The output policy](https://roundel.interlace.tools/docs/guides/output-policy) and
  [Colour levels](https://roundel.interlace.tools/docs/guides/colour-levels) on roundel's
  site.

---

# The plugin system

> One plain object, one published schema, one set of refusal codes, and a check command in every package: how a plugin is written, validated and published across the family.

Source: https://burgee.interlace.tools/docs/concepts/plugins

## What it is

A plugin is a **plain object** with a `name`. Each package in the family reads its own key of
that object and ignores the rest, so one object can extend any subset of the family that is
installed, including all of it: `tokens` for roundel, `widths` for linegauge, `sources` for
seniority, `commands` and `hooks` for burgee, and so on.
[Plugins](/docs/plugins) has the full key-by-key table, generated from the packages.

## Why it exists

Every incumbent extends differently, when it extends at all: a spinner object per ora instance,
a border object per boxen call, middleware on one yargs program, nothing for chalk. A company
that wants the same colours, glyphs and config source in every CLI it ships has to repeat them
per program and per library. One object shape across the family means a convention is written
once and shared by every CLI and every layer.

## How it works

**One schema.** The shape is one JSON Schema (draft 2020-12). Its source is
`packages/flagstaff/src/schema.json`; `npm run schema:sync` copies it byte for byte into every
package that hosts plugins, and each publishes it as `<package>/schema.json`, so an editor, a
validator or a model can read it without running anything. `name` is required,
`additionalProperties` is `true` — which is what lets a package ignore another package's key —
and `contract` is the revision of the object the plugin was written for, currently `1`. Pinned
by `is byte-identical everywhere it is hosted` in
[`plugin-schema-lock.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/scripts/plugin-schema-lock.test.ts).

**One way in.** Eight packages export `register(plugin)` from `<package>/plugin`: bellpull,
caique, closeout, flagstaff, linegauge, paratext, roundel and seniority. burgee takes the same
object through `use(plugin)` on a program — `Manifest#use`, and `.use()` on `burgee/commander`
and `burgee/yargs` — and `definePlugin` from `burgee/plugin` stamps the contract. Each validates
the whole object before it keeps anything, so a refused plugin contributes nothing. That the
same object registers into every host is `one object registers into every host` in
[`plugin-contract-lock.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/scripts/plugin-contract-lock.test.ts).

**One refusal shape.** A refusal is a `PluginError` with a `code`, a `message` and a `fix` — the
sentence that turns a refusal into a next step. The codes every host uses are
`E_PLUGIN_SCHEMA` (the object does not match the schema), `E_PLUGIN_CONTRACT` (a contract newer
than the host knows, or below 1, where the schema starts) and `E_NO_CONTRIBUTION` (it registers, but contributes nothing the host
reads). Packages that draw add `E_NO_STATIC_PROJECTION` — the [static
projection](/docs/concepts/static-projection) rule. flagstaff holds the whole vocabulary, and
[`plugin-error-vocabulary-lock.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/scripts/plugin-error-vocabulary-lock.test.ts)
fails on a code no host's union declares.

## The rules

- **A later registration of the same name wins** in roundel, caique, paratext, bellpull,
  flagstaff and linegauge, and the hosts that report contributions say which one it shadowed.
  closeout's handlers accumulate, ordered by phase. seniority's sources are ordered by rank, and
  at an equal rank the plugin registered later wins (`resolves a tie at an equal rank to the plugin
  registered later` in
  [`plugin.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/seniority/src/plugin.test.ts)).
  burgee refuses a contributed command whose path is already declared.
- **A plugin cannot replace what the host guarantees.** caique's six built-in prompt kinds cannot
  be replaced; closeout refuses a handler in the `restore` phase; a seniority source's rank must
  sit strictly between the flag (0) and the default (40); a burgee plugin's commands pass every
  check a first-party command does, `effects` included.
- **burgee requires `contract`.** An object that reaches `use()` without one is refused, because
  burgee's extension point shipped before it validated anything.
- **A contract below 1 is refused everywhere.** `contract: 0` or a negative number is refused by
  every host, with `E_PLUGIN_CONTRACT` (flagstaff's schema check answers first, with
  `E_PLUGIN_SCHEMA`): `a contract below 1 is refused by every host` in
  [`plugin-contract-lock.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/scripts/plugin-contract-lock.test.ts).
- **A plugin file does not register itself on import.** It exports the object, and the program
  (or `check`) registers it: `refuses a plugin file that registers itself on import, with the
  code and the fix (R8)` in
  [`plugin-check-lock.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/scripts/plugin-check-lock.test.ts).
- **The schema cannot say "function".** `static`, `run` and `read` are required and described;
  that each is a function is checked by the package, not the schema.

## Validating: `<package> check`

Every package ships a `check` command: `npx roundel check ./plugin.mjs`, and the same for each
package. It loads the file, validates and registers the plugin, and prints what that package
does with it, ending in `<name>: ok`. A refusal prints the code and the fix. It exits 0 when
the plugin contributes, 1 on a refusal and 2 on a usage error. `E_NO_CONTRIBUTION` is what
catches a misspelled key: `token` instead of `tokens` is a plugin that contributes nothing.
flagstaff's check also renders each spinner and component in all five output modes, and
`burgee check` returns its report as data, so `--json` gives an envelope. Pinned for seven hosts
by the `$name check` block of `plugin-check-lock.test.ts`.

## Publishing

A plugin is an ES module whose default export is the object, published like any npm package.
There is no plugin registry and no required name prefix: decision
[D-067](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/decisions/D-067.md) chose a
`keywords` convention over an npm namespace. The object should be plain data wherever the schema
allows it, so the published `schema.json` can describe it without running it.

## Run it

One object for three layers:

```js title="acme.mjs"
export default {
  name: 'acme',
  contract: 1,
  tokens: { ok: '#1a7f37', error: '#cf222e' },
  widths: { powerline: { ranges: [[0xe0b0, 0xe0b3]], columns: 2, why: 'powerline glyphs render wide in the company terminal profile' } },
  sources: { vault: { rank: 25, read: () => ({ region: 'eu-1' }), location: 'vault://acme/cli' } },
};
```

Each package's `check` shows only its own part:

```text title="npx roundel check acme.mjs"
acme — 2 tokens
  ok  #1a7f37
  error  #cf222e
acme: ok
```

```text title="npx linegauge check acme.mjs"
acme — 1 widths
  powerline  U+E0B0..U+E0B3  built-in 1 → 2  — powerline glyphs render wide in the company terminal profile
acme: ok
```

A misspelled key, and a contract from the future:

```js title="typo.mjs"
export default { name: 'typo', contract: 1, token: { ok: '#1a7f37' } };
```

```text title="npx roundel check typo.mjs" exit="1"
typo — 0 tokens
E_NO_CONTRIBUTION: typo registers, but contributes nothing roundel reads
  fix: add a `tokens` section — a key another package in the family reads is allowed in the same object, but `roundel check` cannot show it
```

```js title="future.mjs"
export default { name: 'future', contract: 2, tokens: { ok: '#1a7f37' } };
```

```text title="npx roundel check future.mjs" exit="1"
E_PLUGIN_CONTRACT: plugin "future" declares contract 2; this roundel knows 1
  fix: upgrade roundel, or lower the plugin’s contract
```

Registered in code, the same object changes what linegauge measures, and a malformed one is
refused whole:

```js title="widths.mjs"
import { width } from 'linegauge';
import { register } from 'linegauge/plugin';

import acme from './acme.mjs';

console.log(width(' main'));
register(acme);
console.log(width(' main'));

try {
  register({ contract: 1, widths: {} });
} catch (error) {
  console.log(`${error.code}: ${error.message}`);
  console.log(`fix: ${error.fix}`);
}
```

```text title="node widths.mjs"
6
7
E_PLUGIN_SCHEMA: a plugin needs a non-empty `name`
fix: add `name: "my-widths"` — it is what `linegauge check` and a later registration call it
```

## Where the rules live

- [Plugins](/docs/plugins) — every key every package reads, the incumbents' extension points,
  and a nine-layer example, generated from the packages.
- [Fly your own burgee](/docs/your-own-burgee) — the other thing a CLI built on burgee makes its
  own: its flag, from `burgee/brand`.
- Spec: [plugin-contract](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/intents/plugin-contract/spec.md).
- API: each package's `plugin` page, such as
  [`roundel/plugin`](https://roundel.interlace.tools/docs/api/plugin) and
  [`flagstaff/plugin`](https://flagstaff.interlace.tools/docs/api/plugin); guides such as
  [Plugins](https://flagstaff.interlace.tools/docs/guides/plugins) on flagstaff's site.

---

# Shutdown and terminal restore

> closeout's one registry for every way a process leaves: three phases, one deadline for the whole shutdown, the terminal restored last, and a process that dies of the signal it was sent.

Source: https://burgee.interlace.tools/docs/concepts/shutdown

## What it is

[closeout](https://closeout.interlace.tools/docs) keeps **one registry** of exit handlers per
process and runs it, once, whichever way the process leaves. Every package in the family that
changes the terminal — hides the cursor, enters the alternate screen, switches the keyboard to
raw mode — registers the undo here, and nowhere else: the [family's
rules](/docs/concepts/family) make closeout the one owner of signal handlers, exit hooks, the
cursor and raw mode.

## Why it exists

A CLI that dies with the cursor hidden, the alternate screen still up or the keyboard still
raw leaves the user's terminal broken. Each path out needs the same cleanup: a normal exit, a
`process.exit()`, a Ctrl-C, a `SIGTERM` from a supervisor, an uncaught throw, an unhandled
rejection. Before this rule the family had the cursor restore written three times, in
closeout, flagstaff and caique; removing the two copies found that caique never restored the
cursor on a signal at all (the header of
[`inline-implementation-lock.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/scripts/inline-implementation-lock.test.ts)
records it).

## Every exit path

The registry is installed lazily, on the first `onExit`, `hideCursor`, `alternateScreen` or
`rawMode`; importing the package attaches nothing.

| Path | Trigger | After the handlers |
| :-- | :-- | :-- |
| `beforeExit` | the event loop emptied | nothing: the process ends as it would have |
| `exit` | `process.exit()`, or leaving after `beforeExit` | nothing — Node allows no waiting here, so an async handler is started and not awaited |
| `signal` | `SIGINT`, `SIGTERM`, `SIGHUP`, `SIGQUIT`, `SIGBREAK` | the same signal is raised again at the process |
| `uncaught` | an uncaught exception | the error is printed and the process exits 1 |
| `rejection` | an unhandled rejection | the same |

Every handler receives one record, `{ path, signal, code, error }`. A program that installed its
own listener for a signal or a crash keeps it: closeout runs the handlers and leaves the exit
to the program. Pinned by `every door out leaves the terminal as it was found, last` in
[`restore.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/closeout/src/restore.test.ts)
and the exit-path matrix in
[`matrix.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/closeout/src/matrix.test.ts).

## Phases

`onExit(handler, phase)` takes one of three phases, which run in this order:

1. **`flush`** — write what must not be lost: logs, telemetry, a partial result.
2. **`release`** (the default) — close what the program holds: sockets, child processes, locks.
3. **`restore`** — give the terminal back.

A phase starts only when every handler of the one before has settled. Inside a phase all
handlers are started in registration order and then awaited together. A handler that throws
or rejects is reported on stderr and the rest still run. An unknown phase is refused when the
handler is registered. [Plugins](/docs/concepts/plugins) may add handlers to `flush` and
`release` only; `refuses a handler in the restore phase` in
[`plugin.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/closeout/src/plugin.test.ts)
is why "restore last" is a rule and not a convention.

## The deadline

The whole shutdown has **one** clock: 2,000 ms by default, set with `install({ deadline })`.
A deadline that cannot bound anything — `Infinity`, zero, a negative number, `NaN` — is refused
where it is written, as a usage error (`a deadline that cannot bound anything is refused where it
is written` in
[`deadline.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/closeout/src/deadline.test.ts)).

When the deadline passes, closeout stops waiting. The phases not yet reached are still started,
so the terminal is still restored; the report says `timedOut: true` and lists the handlers that
had not returned; and stderr gets one line naming them. The process then leaves the way the
trigger decided: a signal is raised again, a crash exits 1. The deadline never changes the exit
code (`a breached deadline exits with the signal’s code, not with one a handler set on its way
past` in `matrix.test.ts`).

## Restore last

`hideCursor(stream)`, `alternateScreen(stream)` and `rawMode(input)` each make the change and,
in the same call, register its undo in the `restore` phase. Each undo runs at most once, and
calling the returned function early undoes it and unregisters it. A stream that is not a
terminal gets no escape and no registration; raw mode someone else turned on is left on. On
the `exit` path, which cannot wait, a shutdown still waiting on `flush` runs the `restore`
phase synchronously before the process ends (`'exit' arriving before the deadline, while the
shutdown still waits on flush` in `restore.test.ts`).

## A second signal

A shutdown runs once. A second Ctrl-C while the first shutdown is still waiting on a handler
joins the shutdown already in flight rather than starting another or cutting it short; the
process then dies of the **first** signal, after `restore` has run (`a second signal (%s) while
a handler holds the first shutdown` in
[`terminal-restore.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/closeout/src/terminal-restore.test.ts)).
The deadline, not a second signal, is what bounds a hung handler.

## Dying of the signal

After the handlers, closeout removes its listener and sends the process the same signal again.
The process then dies **of** the signal, which is what a shell, `make` or a CI runner reads to
tell "interrupted" from "failed". The POSIX codes (130 for `SIGINT`, 143 for `SIGTERM`, 129 for
`SIGHUP`) are only a fallback, for a runtime that cannot raise a signal at itself (`%s: the
cursor comes back and the process dies of the signal, not of an exit code` in
[`signal.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/closeout/src/signal.test.ts)).
The [exit-code contract](/docs/concepts/exit-codes) counts on this.

## Run it

Phases, not registration order, decide when a handler runs:

```js title="phases.mjs"
import { onExit } from 'closeout';

onExit(() => console.log('restore: last, though it was registered first'), 'restore');
onExit(async () => {
  await new Promise((resolve) => setTimeout(resolve, 20));
  console.log('flush: awaited before release starts');
}, 'flush');
onExit((report) => console.log(`release: path=${report.path} code=${report.code}`));

console.log('work done');
```

```text title="node phases.mjs"
work done
flush: awaited before release starts
release: path=beforeExit code=0
restore: last, though it was registered first
```

A handler that never settles, a deadline of 100 ms, and a `SIGTERM`. The restore still runs,
the hung handler is named, and the process dies of the signal:

```js title="deadline.mjs"
import { install } from 'closeout';

const closeout = install({ deadline: 100 });
closeout.onExit(function flushLogs() {
  return new Promise(() => {}); // never settles
}, 'flush');
closeout.onExit((report) => console.log(`restore: ${report.path} ${report.signal}`), 'restore');

setInterval(() => {}, 1000);
process.kill(process.pid, 'SIGTERM');
```

```text title="node deadline.mjs" signal="SIGTERM"
restore: signal SIGTERM
closeout: shutdown deadline of 100ms expired; exiting anyway. Handlers that had not returned: flushLogs
```

## Where the rules live

- Spec: [closeout R1–R12](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/intents/closeout/spec.md).
- API: [`closeout`](https://closeout.interlace.tools/docs/api),
  [`closeout/cursor`](https://closeout.interlace.tools/docs/api/cursor).
- Guides on closeout's site: [Exit paths](https://closeout.interlace.tools/docs/guides/exit-paths),
  [Phases](https://closeout.interlace.tools/docs/guides/phases),
  [The deadline](https://closeout.interlace.tools/docs/guides/deadline),
  [The terminal](https://closeout.interlace.tools/docs/guides/terminal) and
  [Signals and exit status](https://closeout.interlace.tools/docs/guides/signals).

---

# The static projection

> Every live widget and every terminal capability in the family has a plain-text form for pipes, CI and screen readers — and one without it is refused when it is registered, not discovered when it prints.

Source: https://burgee.interlace.tools/docs/concepts/static-projection

## What it is

Anything the family draws for a terminal — a spinner, a progress bar, a prompt, a hyperlink, an
image — has two forms: the **live** one a terminal sees, and a **static projection**, plain
text that says the same thing to a reader who cannot see the drawing. A pipe, a CI log, a
screen reader and an agent get the static form. The [output policy](/docs/concepts/output-policy)
decides which form a run gets; this page is about what each form must be.

The static form is **required**. The live form is optional.

## Why it exists

Stripping the escapes out of a drawing does not make it text. A progress bar with its colour
removed is still a row of blocks; a box is still a border; a hyperlink with its OSC 8 sequence
removed has lost its destination. The static form is written for a reader, which is why a
built-in says `12/30 files · 40%` rather than `████░░░░`. And a rule every contributor has to
remember is a rule some contribution breaks, so the family checks it at registration: a
component, a widget or a capability without a text form is refused with one code,
`E_NO_STATIC_PROJECTION`, before it can print anything.

## How each package implements it

### flagstaff: components

A component is `{ name, static(state), frame?(t, state), interval? }`. `hoist()` asks
`outputMode` once and picks a projection:

| Mode | What is written | Where |
| :-- | :-- | :-- |
| `tty` | `frame(t, state)` repainted every `interval` ms (80 by default), the cursor hidden; on `lower()`, the final static line | stdout |
| `pipe`, `ci`, `accessible` | `static(state)`, once per change of the text: no carriage return, no cursor escape, and a growing list appended rather than reprinted | stdout |
| `json` | one NDJSON event per transition, `{"event":<name>,"state":<state>}` | stderr |

Under `--json` stdout stays free for the program's own result. Pinned by `R1 · one component,
five modes` and `R5 · off a terminal, no carriage return and no cursor escape` in
[`loop.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/flagstaff/src/loop.test.ts),
and the refusal by `R2 · a contribution without a static projection is refused` in
[`plugin.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/flagstaff/src/plugin.test.ts).
The same applies to a spinner: its `static` string is what a pipe prints instead of the frames.

### paratext: capabilities

A terminal capability is `{ name, osc, when, encode, fallback }`. `emit(runtime, name, fields)`
writes `encode` where `when` says the terminal supports it and `fallback` everywhere else: a
link is `the report (https://…)` in a pipe, never raw OSC and never the text with its
destination dropped. `fallback` is required; an empty string is a legal answer (the bell has
nothing to say in a pipe), absence is not (`refuses a capability with no projection, at
registration rather than at output` in
[`paratext.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/paratext/src/paratext.test.ts)).

paratext is a leaf, so it cannot ask roundel's `outputMode`, and it may not read `CLI_ACCESSIBLE`
or `CI` itself. The mode is handed to it instead: a host that asked `outputMode` passes the answer
as the runtime's `mode`, and anything but `tty` gets the fallback, the same rule flagstaff
follows (`prints the fallback in %s mode, even on a terminal that supports the sequence` in
[`paratext.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/paratext/src/paratext.test.ts)).
Without a `mode`, the built-in capabilities' `when: { tty: true }` is what sends a pipe to the
fallback; `TERM=dumb` always does.

### caique: prompts

A prompt is flags first. When an answer is missing and nobody can type it — `--json`, no
terminal on stdin, `CI`, or an [agent](/docs/concepts/agent-surfaces) — caique does not wait:
it refuses with a `USAGE` verdict that names the flag to pass, which burgee turns into
[exit 2](/docs/concepts/exit-codes). A plugin widget must carry `static(spec)`, the line a pipe,
an agent or a screen reader gets instead of the prompt (``a widget without `static` is
E_NO_STATIC_PROJECTION, the same code flagstaff uses (R5)`` in
[`plugin.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/caique/src/plugin.test.ts);
`R2 · with nobody there, a missing value is an error and never a wait` in
[`decide.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/caique/src/decide.test.ts)).

### controlroom

Reserved, with no API yet. Its spec plans the same rule for full-screen screens: each pane's
static projection in pane order, and NDJSON events on stderr under `--json`.

## What is not the same everywhere

Only flagstaff emits NDJSON under `--json`. caique's answer to `--json` is to refuse the
prompt, which is an envelope rather than an event stream, and paratext has no `--json` form: it
writes the fallback wherever `when` does not match. And paratext knows the mode only when it is
told: `processRuntime()` carries none, so a program that uses paratext on its own, with no host
that asked `outputMode`, still gets the sequence in the `accessible` mode on a terminal. That
default is an open owner decision, raised in
[#754](https://github.com/ofri-peretz/burgee/pull/754).

## Run it

One component and one capability, in a pipe and under `--json`:

```js title="project.mjs"
import process from 'node:process';

import { hoist } from 'flagstaff/loop';
import { emit } from 'paratext';

const rt = {
  env: process.env,
  isTTY: { stdout: process.stdout.isTTY === true },
  stdout: process.stdout,
  stderr: process.stderr,
  clock: {
    now: () => Date.now(),
    schedule(fn, ms) {
      const id = setTimeout(fn, ms);
      return () => clearTimeout(id);
    },
  },
};
const json = process.argv.includes('--json');

const upload = {
  name: 'upload',
  static: (s) => `${s.sent} of ${s.total} files uploaded`,
  frame: (t, s) => `${'|/-\\'[Math.floor(t / 80) % 4]} ${s.sent}/${s.total}`,
};

const flag = hoist(upload, rt, { sent: 0, total: 2 }, { json });
flag.update({ sent: 1, total: 2 });
flag.lower({ sent: 2, total: 2 });

if (!json) console.log(emit(rt, 'link', { text: 'the report', url: 'https://example.com/r/42' }));
```

```text title="node project.mjs"
0 of 2 files uploaded
1 of 2 files uploaded
2 of 2 files uploaded
the report (https://example.com/r/42)
```

```text title="CLI_ACCESSIBLE=1 node project.mjs"
0 of 2 files uploaded
1 of 2 files uploaded
2 of 2 files uploaded
the report (https://example.com/r/42)
```

```text title="node project.mjs --json"
{"event":"upload","state":{"sent":0,"total":2}}
{"event":"upload","state":{"sent":1,"total":2}}
{"event":"upload","state":{"sent":2,"total":2}}
```

A contribution without a text form, in each of the three packages that draw or emit, and a
prompt with nobody to answer it:

```js title="refuse.mjs"
import process from 'node:process';

import { decide } from 'caique/decide';
import { register as registerWidget } from 'caique/plugin';
import { register as registerComponent } from 'flagstaff/plugin';
import { register as registerCapability } from 'paratext';

const attempts = {
  flagstaff: () => registerComponent({ name: 'acme', spinners: { dots: { frames: ['.', '..'], interval: 100 } } }),
  caique: () => registerWidget({ name: 'acme', widgets: { rating: {} } }),
  paratext: () => registerCapability({ name: 'beep', osc: 'BEL', when: { tty: true }, encode: '\u0007' }),
};
for (const [pkg, attempt] of Object.entries(attempts)) {
  try {
    attempt();
  } catch (error) {
    console.log(`${pkg}: ${error.code}`);
  }
}

const verdict = decide({
  value: undefined,
  spec: { kind: 'text', message: 'Project name?' },
  option: 'name',
  runtime: { env: process.env, isTTY: { stdin: process.stdin.isTTY === true } },
  required: true,
});
console.log(verdict);
```

```text title="node refuse.mjs"
flagstaff: E_NO_STATIC_PROJECTION
caique: E_NO_STATIC_PROJECTION
paratext: E_NO_STATIC_PROJECTION
{
  action: 'error',
  code: 'USAGE',
  message: '--name is required when there is no terminal',
  fix: 'pass --name; it would have been asked as "Project name?"'
}
```

## Where the rules live

- The rule: cli-output-stack
  [U3 and R3](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/intents/cli-output-stack/spec.md).
- Guides: [The static projection](https://flagstaff.interlace.tools/docs/guides/static-projection)
  and [Accessibility](https://flagstaff.interlace.tools/docs/guides/accessibility) on flagstaff's
  site; [The static projection](https://paratext.interlace.tools/docs/guides/static-projection) on
  paratext's; [Never hangs](https://caique.interlace.tools/docs/guides/never-hangs) on caique's.
- API: [`flagstaff/loop`](https://flagstaff.interlace.tools/docs/api/loop),
  [`paratext`](https://paratext.interlace.tools/docs/api),
  [`caique/decide`](https://caique.interlace.tools/docs/api/decide).

---

# Width and text correctness

> How linegauge counts the columns a string occupies: grapheme clusters, East Asian Width from Unicode 17 tables, escape sequences that take no columns, and budgets that keep the pathological inputs fast.

Source: https://burgee.interlace.tools/docs/concepts/text-width

## What it is

[linegauge](https://linegauge.interlace.tools/docs) answers one question the rest of the
family asks constantly: **how many terminal columns does this string occupy?** Everything
that aligns a column, wraps a paragraph or cuts a line to fit asks it: burgee's help,
flagstaff's tables and boxes, caique's prompts. Its functions are `width`, `strip`, `wrap`,
`slice`, `truncate` and `widest`, all on the root entry and each but `width` on a subpath of its own
([API](https://linegauge.interlace.tools/docs/api)).

## Why it exists

`.length` counts UTF-16 code units, not columns. `'古池や'.length` is 3 and it occupies 6
columns; `'👨‍👩‍👧'.length` is 8 and it occupies 2; a string wrapped in a colour escape is
longer than what it shows by the escape. A help column measured with `.length` misaligns the
first time a command name is CJK or an emoji, which is how burgee's own help was found doing it
before it took `width` and `widest` from linegauge (`help-width.test.ts` pins that). The
[family's rules](/docs/concepts/family) make linegauge the one owner of the job: a hand-written
measurer, wrapper or stripper anywhere else fails `inline-implementation-lock`.

## How a width is counted

`width(text, { ambiguousIsNarrow = true, countAnsiEscapeCodes = false })`:

1. **A string of printable ASCII is its length.** A non-string or `''` is 0, and a string
   whose every code point is in `0x20`–`0x7E` takes the fast path, which cannot contain an
   escape (`ESC` is `0x1B`). `differential.test.ts` checks that path against the full one on
   a generated corpus.
2. **Escapes are removed.** CSI sequences (introduced by `ESC [` or the C1 byte `U+009B`), SGR
   colours in both the `;` and the `:` forms, and OSC sequences terminated by `BEL` or `ESC \`
   — including OSC 8 hyperlinks — take no columns, unless `countAnsiEscapeCodes: true` asks
   for them to be counted.
3. **Otherwise the text is split into grapheme clusters** with `Intl.Segmenter`, and each
   cluster is measured once, in this order:
   1. a width a [plugin](/docs/concepts/plugins) declared for its code point;
   2. a cluster of only invisible code points (default-ignorable, control, format,
      nonspacing and enclosing marks) is **0**;
   3. an RGI emoji, a keycap, or a ZWJ sequence of two or more pictographs is **2**;
   4. a cluster starting with conjoining Hangul jamo is measured jamo by jamo;
   5. anything else is the East Asian Width of its first visible code point — wide and
      fullwidth are **2**, ambiguous is **1** unless `ambiguousIsNarrow: false` makes it 2 —
      plus any trailing spacing mark or halfwidth/fullwidth form, which takes a column of its
      own.

## Unicode 17, and where the version comes from

The East Asian Width tables in `width.ts` are generated from `get-east-asian-width` 1.7.0,
which is Unicode 17, and pinned exactly in the root `package.json`. It is a development
dependency only: the tables are committed, so nothing installs it.
`generate-width-tables.mjs --check passes` and `measures a Unicode 17 wide code point as two
columns, as string-width does` in
[`width.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/linegauge/src/width.test.ts)
hold the committed tables to the pinned package.

Only the width tables are Unicode 17. Grapheme boundaries (`Intl.Segmenter`) and the
character classes (`\p{RGI_Emoji}`, marks, `\p{Extended_Pictographic}`) come from the running
Node's ICU, which on Node 24 is Unicode 16; the test's own comment says so.

## Escapes are carried, not counted

Measuring skips escapes; cutting and wrapping have to keep them.

- `slice(text, start, end)` cuts by columns and returns a fragment that is **self-contained**:
  it closes every style it opened and reopens a style that was open before the cut. A cut that
  lands inside a wide character or a cluster **rounds inward**, so a slice never returns more
  columns than were asked for (`rounds inward at a wide character, never outward` and `and so
  never returns more columns than were asked for` in
  [`slice.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/linegauge/src/slice.test.ts)).
  OSC 8 links do not nest, so a link that wrapped text is closed before the next opens.
- `wrap(text, columns, { hard, trim, wordWrap })` breaks at word boundaries by default,
  splits a word only with `hard: true`, and carries colours and links across the break (`keeps
  a link and a colour open across the break when an OSC title sits in the row` in
  [`wrap-rows.test.ts`](https://github.com/ofri-peretz/burgee/blob/main/packages/linegauge/src/wrap-rows.test.ts)).
- `truncate(text, columns, { position, ellipsis })` keeps the ellipsis inside the budget.
- `strip(text)` removes every escape, then hands the result to Node's
  `util.stripVTControlCharacters` for the single-character escapes and truncated tails.

## Linear time

A width is computed on every keypress of a prompt and every row of a table, so the worst
input matters as much as the common one. The zero-width check walks code points one at a time
instead of running a backtracking regular expression, and the emoji-sequence scan stops at 50
code units per cluster (`width-scan-limit.test.ts`). The block `zero-width clusters are
measured in linear time, and as the regexes measured them` in `width.test.ts` measures 1,000
joiners before a visible character in under 2 seconds and 3,000,000 joiners in under 15
seconds without a `RangeError`, and checks the loop against the two regular expressions it
replaced on every short string of the classes involved.

Those are time budgets on `width`, not a scaling measurement: no test compares the time at
*n* with the time at *2n*, and `wrap`, `slice`, `truncate` and `strip` have no budget of their
own. `wrap` tracks a row's width instead of remeasuring it per word, and scans for trailing
spaces instead of matching them, for the same reason.

## Run it

```js title="width.mjs"
import { strip, truncate, width, wrap } from 'linegauge';
import slice from 'linegauge/slice';

const samples = {
  ascii: 'hello',
  cjk: '古池や',
  family: '👨‍👩‍👧',
  flag: '🇯🇵',
  combining: 'é',
  styled: '\u001B[1mbold\u001B[22m',
  link: '\u001B]8;;https://burgee.interlace.tools\u0007docs\u001B]8;;\u0007',
  ambiguous: '±',
};
for (const [name, text] of Object.entries(samples)) console.log(`${name.padEnd(10)} ${width(text)}`);
console.log(`ambiguous, CJK terminal: ${width('±', { ambiguousIsNarrow: false })}`);
console.log(JSON.stringify(strip(samples.link)));
console.log(JSON.stringify(wrap('古池や蛙飛び込む水の音', 10, { hard: true })));
console.log(JSON.stringify(slice('古池や', 1, 4)));
console.log(JSON.stringify(truncate('\u001B[31mconfiguration\u001B[39m', 8)));
```

```text title="node width.mjs"
ascii      5
cjk        6
family     2
flag       2
combining  1
styled     4
link       4
ambiguous  1
ambiguous, CJK terminal: 2
"docs"
"古池や蛙飛\nび込む水の\n音"
"池"
"\u001b[31mconfigu\u001b[39m…"
```

`slice('古池や', 1, 4)` asks for columns 1 to 4. `古` occupies 0–1 and `や` 4–5, so neither is
wholly inside the range and only `池` comes back. The truncated string closes its colour
before the ellipsis.

## Where the rules live

- Spec: [linegauge](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/intents/linegauge/spec.md).
- Guides: [Measuring](https://linegauge.interlace.tools/docs/guides/measuring),
  [Wrapping](https://linegauge.interlace.tools/docs/guides/wrapping),
  [Cutting](https://linegauge.interlace.tools/docs/guides/cutting) and
  [Stripping](https://linegauge.interlace.tools/docs/guides/stripping) on linegauge's site.
- Compatibility: string-width, strip-ansi, wrap-ansi and slice-ansi's own suites, graded on
  [Compatibility](/docs/compatibility).

---

# Contrast

> Why your CLI's colours are checked, what AA and AAA actually require, and how to find out which one you meet.

Source: https://burgee.interlace.tools/docs/contrast

A terminal is a display like any other, and a colour that does not read on it excludes the
same people a web page would. `roundel` refuses to fly a theme whose text will not meet
**WCAG AA** against its own declared background — and tells you which token, at which colour
level, by how much.

## Find out where you stand

```ts
import { audit, reportTheme } from 'roundel/theme';

console.log(reportTheme(audit({ ok: '#0a6b47' })));
```

```text
pass  error  truecolor  #f4794a on #0a0a0a  7.24:1 (needs 4.5:1)
pass  error  256        #ff875f on #0a0a0a  8.37:1 (needs 4.5:1)
FAIL  ok     truecolor  #0a6b47 on #0a0a0a  3.02:1 (needs 4.5:1)
pass  ok     256        #008787 on #0a0a0a  4.54:1 (needs 4.5:1)
```

Look at the last two rows: **`ok` fails as truecolor and passes at 256.** Not a glitch — the
cube has no entry as dark as `#0a6b47`, and the substitute it degrades to happens to read. The
colour you wrote is the one to fix; the one the terminal receives is a separate fact, and
collapsing them into a single verdict would hide one of them.

`audit()` returns data and never throws, because knowing should not require catching an
exception. `fly()` is a filter over the same function, so **the refusal and the report cannot
disagree** — a theme is never rejected at startup and reported clean by the audit.

**Passing rows are printed too.** A report that lists only failures cannot tell *"nothing is
wrong"* from *"nothing was checked"*, and the second is the state this package was in for the
256-colour level until 2026-09-13.

## Two colours, not one

The hex you write is not always what the terminal receives. At 256 colours it gets the nearest
entry of the xterm cube, which is a different colour with a different ratio — so both are
checked, at every level, and an `at` column says which is which.

Sweeping the sRGB cube found **167 hexes** that clear 4.5:1 as truecolor and fail once
substituted. `#7e7e7e` is 4.88:1 and becomes `#767676` at 4.36:1.

**There is no row for 16 colours, and there never will be.** At that level a terminal is sent a
*name* — `red`, `greenBright` — and the actual colour is the user's own theme. We do not know
it, so there is no ratio to report, and a number there would be invented.

## AA or AAA

```ts
fly({ conformance: 'AAA' }, runtime);   // 'AA' is the default
```

| | normal text | large text (≥18pt, or ≥14pt bold) |
| :--- | --: | --: |
| **AA** — [SC 1.4.3](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum) | **4.5:1** | 3:1 |
| **AAA** — [SC 1.4.6](https://www.w3.org/WAI/WCAG22/Understanding/contrast-enhanced) | **7:1** | 4.5:1 |

The ratios are not arbitrary. W3C explains 4.5:1 as compensating for vision loss equivalent to
roughly 20/40 acuity, and 7:1 for roughly 20/80 — which is where the two levels differ in
intent rather than in strictness: AA targets the common case, AAA targets low vision directly.

`conformance` raises the floor for **both** jobs at once: the check that refuses a theme, and
the search that picks the 256-colour substitute. A caller asking for AAA must not get a verdict
at one standard and a colour chosen at another.

### Why AA is the default

**Because AA is what the standards and the law actually reference.**

- **EN 301 549**, the harmonised European standard used in public procurement, references
  WCAG 2.1 **Level AA**. It is the basis for conformance under the EU Web Accessibility
  Directive and the European Accessibility Act.
- **Section 508** of the US Rehabilitation Act references WCAG 2.0 **Level AA** as its binding
  baseline, following the 2017 refresh.

And because W3C says so itself, about AAA:

> It is not recommended that Level AAA conformance be required as a general policy for entire
> sites because it is not possible to satisfy all Level AAA success criteria for some content.
>
> — [Understanding Conformance, WCAG 2.2](https://www.w3.org/WAI/WCAG22/Understanding/conformance)

### Why AAA is worth having anyway

A CLI is not a whole site, and the quoted caution is about wholesale policy — not about a
single contrast criterion you can genuinely meet. Turn it on when you know your audience or
your conditions:

- users with low vision, for whom 4.5:1 is the compromise and 7:1 is the target;
- a terminal on a projector, or outdoors, or behind a screen-share re-encode;
- an organisation whose own accessibility policy sets AAA and does not care that this is a
  terminal.

**The cost is measured, not hypothetical.** On a near-black ground, AAA leaves **130 of the 240
addressable palette entries** usable against AA's **179** — a 27% narrower palette. That is why
it is opt-in: defaulting to it would refuse themes that read perfectly well for almost everyone
on almost every terminal.

## What this does not claim

- **Not APCA.** The [APCA](https://github.com/Myndex/SAPC-APCA) critique of WCAG 2.x relative
  luminance is real, and it is sharpest exactly where a terminal lives — dark backgrounds. But
  `4.5` is a WCAG number in a published claim, and swapping the formula would change which
  themes are refused while quietly changing what the claim means. OKLab decides *which* colour
  a hex degrades to; WCAG decides *whether* it is allowed. A perceptual metric may narrow that
  choice and may never widen what `fly()` accepts.
- **Not a full audit of your CLI.** Contrast is one success criterion. Nothing here checks that
  you do not rely on colour alone to convey meaning ([SC 1.4.1](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color)),
  which in a terminal usually means pairing a colour with a glyph or a word — `flagstaff`'s
  accessible mode exists for that, and it is a separate decision from this one.

---

# Gallery

> Every component and every registered plugin, rendered by running them — the static projection beside the animation, in all five modes.

Source: https://burgee.interlace.tools/docs/gallery

Generated by `npm run gallery:page` from what flagstaff has registered. Do not edit by hand.

Every cell on this page is produced by **running** the component, through the same
`hoist()` a program uses and the same code path as `flagstaff check` — not by describing
it. Escapes are shown as `␛`, carriage returns as `␍` and newlines as `⏎`, so what a
terminal would swallow is visible.

## The five modes

One component, five answers. The `tty` row is the animation; every other row is the
**static projection**, and it is the artifact — what a pipe, a CI log, an agent and a
screen reader all read. Notice that no other row contains an escape sequence.

### spinner

The running glyph and the text, then the settled glyph — never a frame.

| mode | what it writes |
| :-- | :-- |
| `tty` | `␛[?25l␛[?2026h⠋ building␛[?2026l␛[?2026h␛[1G␛[0J⠙ building␛[?2026l␛[?2026h␛[1G␛[0J⠹ building␛[?2026l␛[?2026h␛[1G␛[0J⠸ building␛[?2026l␛[?2026h␛[1G␛[0J✔ built␛[?2026l⏎ ␛[?25h` |
| `pipe` | `… building⏎ ✔ built⏎` |
| `ci` | `… building⏎ ✔ built⏎` |
| `json` | `{"event":"spinner","state":{"text":"building"}}⏎ {"event":"spinner","state":{"text":"built","status":"ok"}}⏎` |
| `accessible` | `… building⏎ ✔ built⏎` |

### progress

The count and the percentage; a bar of blocks says nothing in a log.

| mode | what it writes |
| :-- | :-- |
| `tty` | `␛[?25l␛[?2026h█████░░░░░░░ 12/30 files␛[?2026l␛[?2026h␛[1G␛[0J30/30 files · 100%␛[?2026l⏎ ␛[?25h` |
| `pipe` | `12/30 files · 40%⏎ 30/30 files · 100%⏎` |
| `ci` | `12/30 files · 40%⏎ 30/30 files · 100%⏎` |
| `json` | `{"event":"progress","state":{"done":12,"total":30,"label":"files"}}⏎ {"event":"progress","state":{"done":30,"total":30,"label":"files"}}⏎` |
| `accessible` | `12/30 files · 40%⏎ 30/30 files · 100%⏎` |

### tasks

Only what has settled, so a pipe is not told twice that a step is running.

| mode | what it writes |
| :-- | :-- |
| `tty` | `␛[?25l␛[?2026h✔ install⏎ ⠋ build␛[?2026l␛[?2026h␛[1G␛[0J⠙ build␛[?2026l␛[?2026h␛[1G␛[0J⠹ build␛[?2026l␛[?2026h␛[1G␛[0J⠸ build␛[?2026l␛[?2026h␛[1G␛[0J✔ build␛[?2026l⏎ ␛[?25h` |
| `pipe` | `✔ install⏎ ✔ build⏎` |
| `ci` | `✔ install⏎ ✔ build⏎` |
| `json` | `{"event":"tasks","state":{"tasks":[{"title":"install","status":"ok"},{"title":"build","status":"running"}]}}⏎ {"event":"tasks","state":{"tasks":[{"title":"install","status":"ok"},{"title":"build","status":"ok"}]}}⏎` |
| `accessible` | `✔ install⏎ ✔ build⏎` |

### box

The title and the text; a border is noise a screen reader reads character by character.

| mode | what it writes |
| :-- | :-- |
| `tty` | `␛[?25l␛[?2026h╭─ dev ──────────────────────────╮⏎ │ starting                       │⏎ ╰────────────────────────────────╯␛[?2026l␛[?2026h␛[1G␛[2A␛[0Jdev: ready on :3000␛[?2026l⏎ ␛[?25h` |
| `pipe` | `dev: starting⏎ dev: ready on :3000⏎` |
| `ci` | `dev: starting⏎ dev: ready on :3000⏎` |
| `json` | `{"event":"box","state":{"text":"starting","title":"dev"}}⏎ {"event":"box","state":{"text":"ready on :3000","title":"dev"}}⏎` |
| `accessible` | `dev: starting⏎ dev: ready on :3000⏎` |

### table

One line per row of header-and-value pairs, parseable without knowing the drawing.

| mode | what it writes |
| :-- | :-- |
| `tty` | `␛[?25l␛[?2026h┌──────┬───────┐⏎ │ host │ tests │⏎ ├──────┼───────┤⏎ │ ora  │ 99    │⏎ └──────┴───────┘␛[?2026l␛[?2026h␛[1G␛[4A␛[2Khost: ora, tests: 99␛[1G␛[1B␛[0Jhost: log-update, tests: 99␛[?2026l⏎ ␛[?25h` |
| `pipe` | `host: ora, tests: 99⏎ host: log-update, tests: 99⏎` |
| `ci` | `host: ora, tests: 99⏎ host: log-update, tests: 99⏎` |
| `json` | `{"event":"table","state":{"rows":[["ora","99"]]}}⏎ {"event":"table","state":{"rows":[["ora","99"],["log-update","99"]]}}⏎` |
| `accessible` | `host: ora, tests: 99⏎ host: log-update, tests: 99⏎` |

## Spinner styles

What the registry holds right now. `static` is what every mode but `tty` prints; a style
without one is refused at `register()`.

| style | static | frames | interval |
| :-- | :-- | :-- | --: |
| `dots` | `…` | `⠋` `⠙` `⠹` `⠸` `⠼` `⠴` `⠦` `⠧` | 80 ms |
| `line` | `…` | `-` `\` `\|` `/` | 130 ms |

Two, because two is what the package ships. The corpus everyone already has is one line
away and is **not** bundled — `fromCliSpinners(cliSpinners)` adds 88 more
(`dots2`, `dots3`, `dots4`, `dots5`, `dots6`, `dots7`, …), each with `…` as its static
projection unless you say otherwise:

```js
import cliSpinners from 'cli-spinners';
import { fromCliSpinners } from 'flagstaff/import';
import { register } from 'flagstaff/plugin';

register(fromCliSpinners(cliSpinners));
```

## Borders

Drawn by `box()`, from the same registry. `fromCliBoxes(cliBoxes)` adds the rest of that
corpus the same way.

```text
round
╭────────────────────────────────╮
│ box('…', { border: 'round' })  │
╰────────────────────────────────╯
```

```text
single
┌────────────────────────────────┐
│ box('…', { border: 'single' }) │
└────────────────────────────────┘
```

```text
double
╔════════════════════════════════╗
║ box('…', { border: 'double' }) ║
╚════════════════════════════════╝
```

```text
bold
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ box('…', { border: 'bold' })   ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
```

```text
classic
+--------------------------------+
| box('…', { border: 'classic'   |
| })                             |
+--------------------------------+
```

```text
none
 box('…', { border: 'none' })     
```

## Writing one of your own

A plugin is one plain object, validated against [`schema.json`](https://github.com/ofri-peretz/burgee/blob/main/packages/flagstaff/src/schema.json) — the same file that ships in the tarball:

```js
export default {
  name: 'pulse',
  contract: 1,
  spinners: {
    pulse: { frames: ['◜', '◝', '◞', '◟'], interval: 90, static: '…' },
  },
};
```

```bash
npx flagstaff check ./pulse.mjs
```

`check` prints exactly the table at the top of this page for whatever you wrote, and exits
1 with the code and a fix if the schema refuses it. Leave the `static` off and it says so:

```text
E_NO_STATIC_PROJECTION: pulse has no static projection
  fix: give it a `static`: the text a pipe, an agent or a screen reader gets instead of the animation
```

---

# Getting started

> One file, one command, and your agent connected to it while you write it.

Source: https://burgee.interlace.tools/docs/getting-started

## 1. Start it

```bash
npx burgee init my-cli && cd my-cli && npm install
node cli.mjs --name ada                # greeting: hello, ada
```

`init` writes two files: `cli.mjs`, the quick start from burgee's README, and a `package.json`
that runs it. `--install` runs the install too, with the package manager you ran `init` under.
Nothing it writes refers back to `init`.

## 2. Write the CLI

One file. No build step, no directory layout.

```ts
// cli.ts
import { defineCommand, defineProgram, run } from 'burgee';

export const program = defineProgram({
  name: 'hello',
  commands: [
    defineCommand({
      name: 'greet',
      description: 'Greet someone',
      effects: 'read_only',
      arguments: [{ name: 'name', required: true }],
      options: { shout: { type: 'boolean', description: 'uppercase it' } },
      run: ({ positionals, options }) => {
        const line = `Hello, ${positionals[0]}`;
        return options.shout ? line.toUpperCase() : line;
      },
    }),
  ],
});

if (import.meta.main) await run(program);
```

Already on commander or yargs? Swap the import for `burgee/commander` or `burgee/yargs` and
export the `Command` or the yargs instance as `program`. Nothing else changes.

## 3. Keep your agent connected while you write it

```bash
npx burgee dev ./cli.ts
```

`burgee dev` serves the program as an MCP server on stdio and watches the entry. On every
save it re-imports the file as a fresh module graph, swaps the served tools, sends
`notifications/tools/list_changed` so a connected client re-lists, and prints on stderr
what changed and the rendered help. Point your agent's MCP configuration at that command
and it sees a command the moment it is written — no rebuild, no restart.

It is a developer tool and nothing more: a CLI built without ever running it is byte for
byte the same, and nothing a shipped CLI imports can reach it.

## 4. Everything else is already there

```bash
node cli.ts greet ada --shout          # HELLO, ADA
node cli.ts greet ada --json           # {"ok":true,"data":"Hello, ada","meta":{...}}
node cli.ts --schema                   # the program as JSON Schema
node cli.ts --mcp                      # the same server, without the watcher
node cli.ts completion zsh             # a static completion script
```

Every one of those is a projection of the declaration above. See
[agent surfaces](/docs/agent-surfaces) for what each one carries.

---

# Overview

> burgee serves one command declaration as help, --json, --schema, an MCP server, completions and types; answers an agent with exit codes, fix: lines and --explain; takes no dependency outside its family; and grades each drop-in path by the incumbent's own test suite.

Source: https://burgee.interlace.tools/docs

**burgee** is a CLI framework built on one declaration. You declare a command once, and
help, `--json`, `--schema`, an MCP server, shell completions and TypeScript types are all read
from that declaration, so none of them can drift from the others.

```text
defineCommand()  ──▶  manifest  ──┬──▶  human help
                                  ├──▶  --json      one stable envelope
                                  ├──▶  --schema    versioned, one document per surface
                                  ├──▶  --mcp       an MCP server, generated
                                  ├──▶  completions bash · zsh · fish · pwsh
                                  ├──▶  TypeScript types
                                  └──▶  docs + llms.txt
```

## Contracts an agent can act on

An agent calling a CLI through a shell pays in calls, tokens and misreads. A burgee command
gives it contracts instead of prose to interpret:

- a stable `{ ok, data }` envelope under `--json`, and a versioned schema under `--schema`;
- an exit code that says *rewrite the command* (`2`) rather than *something went wrong*;
- a `fix:` line on a mistyped command, which the agent can run as written;
- `--explain <option>`, which says whether a value came from a flag, an environment
  variable, a config file or a default;
- the same commands as MCP tools under `--mcp`.

[Your CLI is an agent tool](/docs/agent-surfaces) has each surface, and
[What an agent sees](/docs/what-an-agent-sees) has recorded sessions of a model using them.

## One supply chain

Ten packages, one repository, one release pipeline, and no dependency outside the burgee
family in any of them. Six take nothing at all; the other four take only each other.
[Packages](/docs/packages) has each one. Every release is published with npm provenance and
no npm token, and what installing each package brings in is listed on
[Supply chain and continuity](/docs/supply-chain).

## Proved by each incumbent's own suite

Every drop-in path is graded by the original package's own test suite, vendored
unmodified apart from the import specifier and run in CI beside a control that runs the real
package. The rates are on [Compatibility](/docs/compatibility), generated, never hand-edited.
The [benchmarks](/docs/benchmarks) publish every comparison, the rows burgee loses included.

## Start in one command

```bash
npx burgee init my-cli && cd my-cli && npm install
```

It writes `cli.mjs` and a `package.json`, and nothing else.
[Getting started](/docs/getting-started) goes on from there.

## Switch in one command

```bash
npx burgee migrate --dry-run
npx burgee migrate
```

burgee has drop-in paths for commander and yargs, and the family has them for chalk, ora,
string-width and the other packages graded level with their own suites. `burgee migrate` rewrites the import
specifiers and nothing else, then prints the install command to run next. For one commander
program, that is one line:

```diff
- import { Command } from 'commander';
+ import { Command } from 'burgee/commander';
```

[Migrate](/docs/migrate) has the whole report, and [Switching from commander](/docs/vs/commander)
and [Switching from yargs](/docs/vs/yargs) go through each API.

## Where to go next

- [Getting started](/docs/getting-started) — one file, one command, and an agent connected
  to it while you write it.
- [Why it's built this way](/docs/why) — the five choices behind the family, what each one
  gives you, and what it does not claim.
- [Concepts](/docs/concepts) — how the family works on its own terms: the layers, the output
  policy, plugins, exit codes, shutdown, configuration, and how each claim is proven.
- [Packages](/docs/packages) — the ten packages of the family, each with no dependency
  outside it, each with its own incumbents and its own site.
- [Compatibility](/docs/compatibility) — every host suite, every pass rate, generated.
- [Your CLI is an agent tool](/docs/agent-surfaces) — `--schema`, `--mcp`, completions and
  `--explain`.
- [The floor](/docs/the-floor) — the requirements every CLI on burgee meets.

For agents: [`/llms.txt`](/llms.txt) is the map, [`/llms-full.txt`](/llms-full.txt) the
whole corpus, and every page has a Markdown twin at its own URL plus `.md`. The source and
the research behind every claim are on
[GitHub](https://github.com/ofri-peretz/burgee/tree/main/.sdlc/research).

---

# Migrate

> One command moves a project from commander, yargs, chalk, ora and a dozen more incumbents to the family's drop-ins — every import the compatibility oracle grades level, and nothing it does not.

Source: https://burgee.interlace.tools/docs/migrate

```bash
npx burgee migrate --dry-run
npx burgee migrate
```

`burgee migrate` rewrites import specifiers, and only specifiers: `'chalk'` becomes
`'roundel/chalk'`, `'commander'` becomes `'burgee/commander'`, and the code around them is
left exactly as it was. It then prints what it changed, what it would not change and why,
the family packages to add, and the one command that adds them and removes the incumbents —
for the package manager your lockfile names, each family package pinned to the version that
carries the graded drop-in:

```text
next: npm install burgee@^X flagstaff@^Y roundel@^Z && npm uninstall commander chalk ora
```

`X`, `Y` and `Z` are the versions this burgee was built beside, read from each package's own
manifest at build time; [Run it](/docs/concepts/drop-ins#run-it) shows a real run. Unpinned, a package manager is free to pick an older release that
predates the drop-in; under pnpm's `minimumReleaseAge` one did exactly that. When your
project sets a minimum release age (`minimumReleaseAge` in `pnpm-workspace.yaml`, or
`minimum-release-age` in `.npmrc`), the report says so under `releaseAge`: a graded version
younger than the rule allows will not install. `next` then pins the newest release old enough,
but never one older than the first release that exports every subpath the rewrite imports:
`roundel/picocolors` first shipped in roundel 1.1.0, so a project moved onto it is never pinned
to `roundel@^1.0.4`. When no release is both old enough and carrying the subpath, the note says
which subpath and the date the first one that does becomes installable.

The first line of the report says how it went — `complete: 3 files rewritten`,
`partial: 2 files rewritten, 1 refused`, `blocked: 1 preflight check; nothing written (3 files
would be rewritten)`, or `nothing to rewrite` — and the rest is the detail, as text. `--json`
gives the same report as data, with that line as `summary`. The command exits 1 when anything
was refused or blocked, so an agent can run it unattended and branch on the result. A refused run is partial, not undone: the files that could move have moved, and the
summary says how many.

## What it moves, and what you choose

By default it moves the incumbents your `package.json` declares — in `dependencies`,
`devDependencies`, `optionalDependencies` or `peerDependencies`. An incumbent your code
imports without declaring it, because it arrives through another package (`@inquirer/core`
through `@inquirer/confirm`, say), is listed under `undeclared` and left alone. Two flags
change the choice, both taking incumbent package names, comma-separated or repeated:

```bash
npx burgee migrate --only chalk,ora      # these and nothing else, declared or not
npx burgee migrate --skip @inquirer/core  # everything it would move, except these
```

A name it does not migrate is a usage error, exit 2, with the list of names it does.

## What it rewrites

Every drop-in the [compatibility oracle](/docs/compatibility) grades **level** with its
incumbent: the incumbent's own test suite passes at least as many cases against the family's
replacement as against the incumbent itself, run in the same harness. The grades live on that
page and move as it moves; this list is the codemod's own table, and a lock holds the two
equal.

| incumbent | becomes |
| :-- | :-- |
| `commander` | `burgee/commander` |
| `@commander-js/extra-typings` | `burgee/commander/extra-typings` |
| `yargs` | `burgee/yargs` |
| `yargs/yargs` | `burgee/yargs` |
| `yargs/helpers` | `burgee/yargs/helpers` |
| `yargs-parser` | `burgee/yargs/parser` |
| `chalk` | `roundel/chalk` |
| `ora` | `flagstaff/ora` |
| `log-update` | `flagstaff/log-update` |
| `boxen` | `flagstaff/boxen` |
| `cli-table3` | `flagstaff/cli-table3` |
| `string-width` | `linegauge` |
| `strip-ansi` | `linegauge/strip` |
| `wrap-ansi` | `linegauge/wrap` |
| `slice-ansi` | `linegauge/slice` |
| `cross-spawn` | `bellpull/cross-spawn` |
| `ansi-escapes` | `paratext` |
| `which` | `bellpull/node-which` |
| `rc` | `seniority/rc` |
| `lilconfig` | `seniority/lilconfig` |
| `cosmiconfig` | `seniority` |
| `dotenv` | `seniority/dotenv` |
| `dotenv/config` | `seniority/dotenv/config` |
| `dotenv/config.js` | `seniority/dotenv/config` |
| `find-up` | `seniority/find-up` |
| `onetime` | `closeout/onetime` |
| `cli-cursor` | `closeout/cli-cursor` |
| `cli-truncate` | `linegauge/cli-truncate` |
| `widest-line` | `linegauge/widest-line` |
| `picocolors` | `roundel/picocolors` |
| `supports-color` | `roundel/supports-color` |
| `yoctocolors` | `roundel/yoctocolors` |
| `@clack/prompts` | `caique/clack` |
| `@inquirer/core` | `caique/inquirer` |
| `@inquirer/prompts` | `caique/inquirer/prompts` |
| `meow` | `burgee/meow` |
| `terminal-link` | `paratext/terminal-link` |
| `term-img` | `paratext/term-img` |
| `restore-cursor` | `closeout/restore-cursor` |
| `exit-hook` | `closeout/exit-hook` |
| `signal-exit` | `closeout/signal-exit` |
| `signal-exit/signals` | `closeout/signal-exit/signals` |
| `ink` | `controlroom/ink` |

A test's mocks move with the imports they mock. The first argument of `vi.mock`,
`vi.doMock`, `vi.unmock`, `vi.doUnmock`, `vi.importActual`, `vi.importMock`, `jest.mock`,
`jest.doMock`, `jest.unmock`, `jest.requireActual`, `jest.requireMock`,
`jest.unstable_mockModule` and `require.resolve` is a specifier like any other, type arguments
included (`vi.importActual<typeof import('chalk')>('chalk')`). A mock left on `chalk` while the
code imports `roundel/chalk` mocks a module nothing loads, and the tests that relied on it fail.

ink brought `react-reconciler` in as its own dependency; `controlroom/ink` takes it as an
optional peer, so for an ink program the `next` command installs it beside `controlroom`.
The rewrite is for ink 8, the major whose own suite grades `controlroom/ink` level (1304 of
1304 cases). A project still on ink 6 is listed under `offMajor` and left alone: ink 6's suite
grades the drop-in 540 of 584, because it follows ink 8 where the two majors disagree.

## What it leaves alone, and says so

- **An incumbent it cannot move everywhere.** An incumbent moves in every file or in none.
  When one file is refused, every incumbent that file imports stays imported there, so each
  of them is listed under `held`, with the files that hold it, and rewritten in no file. The
  same goes for an import kept on the incumbent. Moving the rest would put two copies of the
  incumbent in one program, and a class from one is not `instanceof` the other's: a prompt
  cancelled with Ctrl+C throws one `ExitPromptError`, the `catch` tests for the other, and the
  program prints an error where it used to exit 0.
- **An error class another dependency still throws.** When a dependency your `package.json`
  declares depends on the incumbent itself — `@inquirer/confirm` depends on `@inquirer/core` —
  the incumbent stays installed after the migration, and the report lists it under
  `transitive` with the dependencies and the replacement's error classes. That dependency
  throws the incumbent's classes, never the replacement's, so an import that names one of
  them (`ExitPromptError`, `CommanderError`, `YError` …) is kept on the incumbent, and so is
  one whose names cannot be read (`import * as`, `require()`). Kept, it holds the incumbent as
  above. A type-only import compares nothing at run time, and moves.
- **A drop-in that is not level yet.** Every graded drop-in is level today. One that passes
  fewer of its incumbent's cases than the incumbent does is listed under `partial` with the
  grade, and never rewritten: a codemod that breaks your CLI is worse than none.
- **A name the replacement does not export.** Every imported name is checked against the
  replacement's exports. A type-only import of a missing name stays on the incumbent, with a
  note to keep its types installed; a value import of one refuses the file.
- **An incumbent on a major the oracle did not grade.** The grade is for one major:
  `signal-exit` 3 exports a function where 4 exports `onExit`, and `chalk` 4 is CommonJS where
  6 is not. A project whose installed version — or, with nothing installed, whose declared
  range — is on another major is listed under `offMajor` with both versions, and not
  rewritten. For commander and yargs the row also says what stands between it and a move:
  see [When your incumbent is on an older major](#when-your-incumbent-is-on-an-older-major).
- **A `require()` whose two sides return different kinds of value.** `require()` of an ES
  module returns its namespace. The incumbents that ship ESM only (chalk 6, ora 9, boxen 9 and
  ten more) already hand `require()` a namespace, and so do their replacements, so
  `const chalk = require('chalk')` moves. Where the incumbent hands back its export itself — a
  function or a class — and the replacement would hand back a namespace, the file is refused
  with `require-of-default`. No current replacement is in that position: each one whose
  incumbent returns a function exports it as `'module.exports'`, which is what Node hands a
  CommonJS caller. `const { Command } = require('commander')` moves, because it reads names.
- **A clack file that also imports `@clack/core`.** `@clack/prompts` reads its settings from
  `@clack/core`, and `caique/clack` does not depend on it. So once the prompts move, an
  `updateSettings` imported from `@clack/core` changes settings nothing reads. A file that
  imports `@clack/prompts` and imports, `import()`s or `require()`s `@clack/core` is refused
  with `sibling-state`, and the refusal carries its `fix`:
  `import { updateSettings } from 'caique/clack' instead of '@clack/core', then re-run burgee migrate`.
  A type-only import of `@clack/core` configures nothing and does not refuse. A file that
  imports `@clack/core` and not `@clack/prompts` is not rewritten, so it is not refused either.
  The check reads one file at a time: an `updateSettings` from `@clack/core` in a file with no
  clack prompts is not seen.
- **A deep import** (`commander/lib/command.js`) or **a specifier that is not a literal**
  (`require(name)`). The file is refused by name and line, and left exactly as it was — a
  file is rewritten whole or not at all — and its incumbents are held. A mock or a
  `require.resolve` whose argument is not a literal is not refused: it loads nothing into
  the program.

  Three computed shapes load your own file or your user's module, never an incumbent, so they
  are not refused, and are listed under `dynamic` (`read as not an incumbent`) instead:

  - a path from the working directory: `require(path.join(process.cwd(), 'package.json'))`, or
    `path.resolve`, or from `__dirname`, followed by string literals only;
  - a member of a parsed argv object: `import(argv.parser)`, and `args`, `options`, `opts` or
    `flags`;
  - an element of an argv array: `argv.use.map(async (plugin) => import(plugin))`, and `forEach`,
    `flatMap` or `filter`.

  A string anywhere in the file that names an incumbent being moved (`'chalk'`,
  `'node_modules/chalk'`, `` `${dir}/chalk` ``) could be what a computed name is built from. Every
  computed specifier in that file is then refused, and the file holds that incumbent too, even if
  it does not import it.
- **A dirty git tree**, unless you pass `--force`, so the rewrite is one reviewable diff. The
  command exits 1 and writes nothing, and its `hint` lists the paths `git status` printed, so an
  install that left an untracked cache behind is named. When every one of them is untracked, the
  `fix` says to add them to `.gitignore` or commit them. `--dry-run` writes nothing either way, so
  it skips the check, and a directory that is not a git repository has nothing to be dirty.

## When your incumbent is on an older major

Most commander and yargs CLIs are not on the major the drop-in claims, and moving one by hand
is how four of them crashed in our field trial: each used an API its own incumbent removed in a
later major. So for commander and yargs, an `offMajor` row carries three more fields:

- `sites`: every line that uses an API the incumbent removed after your major, up to the
  highest major the drop-in claims. Each has its `file`, `line`, `api`, the release that removed
  it (`removedIn`), the line to write instead (`replacement`), and the incumbent's own changelog
  entry (`source`). A binding such as `const program = require('commander')` is one site, at the
  line that makes it, with `firstUse`, the first line that uses it as what is gone.
- `nearest`: the smallest major the drop-in claims above yours: 14 for commander 13 and older, and
  17 for yargs 16 and older.
- `move`: each specifier you import, with the entry it moves to at `nearest`
  (`{ "yargs": "burgee/yargs/v17" }`), when no site's API was gone by that major and every
  specifier you import has an entry there. Otherwise it is `null`, and the lines in the way are
  the sites removed at or before `nearest`. A deep import, or `commander/esm.mjs`, has no entry,
  so it stops the move too.

Nothing is rewritten: the major you are on was not graded, so this is a work list, not a
rewrite. The first line says so: `nothing to rewrite; 1 line uses an API a claimed major
removed (see offMajor)`. The move is checked against these seven APIs and nothing else. It is
graded at `nearest`, not at your major, so the rest of the incumbent's own changelog between
the two still applies.

| API | Removed in | Use instead |
| :-- | :-- | :-- |
| `module-as-program` | [commander 12.0.0](https://github.com/tj/commander.js/blob/v15.0.0/CHANGELOG.md#1200-2024-02-03) | `const { program } = require('commander')` |
| `multi-char-short-flag` | [commander 13.0.0](https://github.com/tj/commander.js/blob/v15.0.0/CHANGELOG.md#1300-2024-12-30) | a one-character short flag, or the long flag alone |
| `esm-mjs` | [commander 15.0.0](https://github.com/tj/commander.js/blob/v15.0.0/CHANGELOG.md#1500-2026-05-29) | `import { program } from 'commander'` |
| `rebase` | [yargs 16.0.0](https://github.com/yargs/yargs/blob/v18.0.0/CHANGELOG.md#1600-2020-09-09) | `path.relative()` |
| `reset` | [yargs 17.0.0](https://github.com/yargs/yargs/blob/v18.0.0/CHANGELOG.md#1700-2021-05-02) | a fresh `yargs()` instance |
| `on-finish-command` | [yargs 17.0.0](https://github.com/yargs/yargs/blob/v18.0.0/CHANGELOG.md#1700-2021-05-02) | await the promise the command's handler returns |
| `singleton` | [yargs 18.0.0](https://github.com/yargs/yargs/blob/v18.0.0/CHANGELOG.md#1800-2025-05-26) | `require('yargs/yargs')(process.argv.slice(2))` |

The command also reads each file your `package.json` `bin` names, so an extensionless
`bin/cli` is checked, and moved on a claimed major, like any other source file.

## What it checks before it writes

Moving to the family changes what your package needs from the Node that runs it and from its test
runner. Before it writes anything, the command reads your `package.json` (`type`, `engines.node`,
`scripts.test`, a `jest` key) and any `jest.config.*` beside it, and lists what the move costs
under `preflight`, first in the text report under `before the move`:

| check | kind | when |
| :-- | :-- | :-- |
| `require-esm` | block | the package is CommonJS and `engines.node` allows a Node on which `require()` of an ES module throws `ERR_REQUIRE_ESM`: below 20.19.0, or 21.0.0 to 22.11.x |
| `floor` | warn | `engines.node` allows a Node below 20.19.0, cannot be read, or is not declared. Adopting raises your package's floor, which is a semver-major for it |
| `jest-cjs` | block | jest runs a CommonJS package, with neither `transformIgnorePatterns` nor `--experimental-vm-modules`: jest's own module loader cannot load an ES-module-only drop-in |
| `untracked` | warn | `--force` let untracked paths through; they are named, so the report records what it ignored |

Each row has the `found` text it read, a `message`, and a `fix`. For `require-esm` and `floor` the
fix is `npm pkg set "engines.node=^20.19.0 || >=22.13.0"`, the floor every family package
declares. For `jest-cjs` it is the `transformIgnorePatterns` that lets jest transform the family's
packages, or running jest under `node --experimental-vm-modules`. The command runs neither: it
rewrites specifiers and nothing else.

A blocking row means the rewritten project would not load on a Node its own `engines` allows, or
under its own tests. When one applies and the run would rewrite a file, nothing is written, the
summary starts `blocked:`, and the command exits 1. `--force` does not lift it: `--force` skips
the git-tree check and nothing else. A run with nothing to rewrite still prints the rows, and
exits as it would have. The rows cover every incumbent you depend on, including one on a major
the oracle did not grade, because what adopting costs does not depend on which major you are on.

## Exit codes

| Code | When |
| ---: | :-- |
| 0 | nothing was refused — `complete: …` or `nothing to rewrite`. Held, kept, undeclared and off-major incumbents are reported and are not failures. |
| 1 | something was refused — `partial: N files rewritten, M refused` — or a blocking preflight check stopped the write (`blocked: …`), or the git tree is dirty and nothing was written. The report is printed either way. |
| 2 | `--only` or `--skip` named a package it does not migrate; nothing was read or written. |

## What it reports, and never rewrites

**blessed, neo-blessed and terminal-kit** have no drop-in. Their surfaces are too large to
reproduce honestly, and a screen moved onto controlroom is a different shape, not a
substitution. So the command finds their screen, box, list and key sites and lists each under `guided`, with
the file, the line, the pattern and the section of that incumbent's coming-from guide. It
rewrites none of them, and they do not change the exit code, because nothing was refused.

A site is reported only when its receiver came from one of the three in the same file:
`screen.key(` is a key binding when `screen` came from `blessed.screen()`, and is not
otherwise. A screen passed in from another file is not followed; that file's import of the
package still is.

| pattern | blessed and neo-blessed | terminal-kit | guide section |
| :-- | :-- | :-- | :-- |
| `import` | `require`, `import`, `import()` | the same | the mapping |
| `screen` | `screen()`, `program()` | `createTerminal()`, `ScreenBuffer` | Screen |
| `alternate-screen` | `alternateBuffer()`, `normalBuffer()` | `fullscreen()` | Alternate screen |
| `box` | `box()`, `text()`, `element()`, `log()`, `layout()` | — | Box |
| `list` | `list()`, `listtable()`, `listbar()` | `singleColumnMenu()` and the other menus | List |
| `key` | `key()`, `onceKey()`, `unkey()`, `removeKey()`, a `key…` event | `grabInput()`, a `key` event | Key handling |
| `render` | `render()` | a screen buffer's `draw()` | Render loop |
| `mouse` | `enableMouse()`, a mouse event | the `mouse` option, a mouse event | Mouse |
| `text-input` | `textbox()`, `textarea()` | `inputField()` | Text editing in a pane |

The guides are [Coming from blessed](/docs/coming-from/blessed),
[Coming from neo-blessed](/docs/coming-from/neo-blessed) and
[Coming from terminal-kit](/docs/coming-from/terminal-kit).

## Why an import, not `overrides`

An npm `overrides` entry points an incumbent's name at a package's **root**, and each family
package's root is its own API, not any one incumbent's. The replacements are subpaths, which
an override cannot reach, so the swap is the import — which is also the change your reviewers
can see.

---

# burgee

> A CLI framework built on one declaration: help, --json, --schema, MCP, completions and types are projected from it, with exit codes and fix: lines an agent can act on. No dependency outside the burgee family. Drop-in paths for commander, yargs and meow.

Source: https://burgee.interlace.tools/docs/packages/burgee

**burgee** is a CLI framework built on one declaration. A command declares itself once, and
help, `--json`, `--schema`, an MCP server, shell completions and TypeScript types are all read
from it. An agent gets contracts rather than prose: exit `2` means *rewrite the command*, a
mistyped command comes back with a `fix:` line it can run, and `--explain` says where each
value came from. Five dependencies, all from the burgee family, and no dependency outside it.

Drop-in for **commander** and **yargs**: `npx burgee migrate` rewrites the imports to
`burgee/commander` and `burgee/yargs`, graded by each one's own test suite, and the same
program answers agents too.

A **burgee** is the small swallowtail flag a boat flies to say which club or fleet it
belongs to — a flag of identity, not of instruction. That is what this framework does for
a command-line program: a command declares itself once, and every surface is that
declaration read by a different reader.

## Install

```bash
npm install burgee
pnpm add burgee
yarn add burgee
bun add burgee
```

## Quick start

```bash
npx burgee init my-cli && cd my-cli && npm install
```

`init` writes this file as `cli.mjs`, and a `package.json` that runs it. Nothing else.

```js
#!/usr/bin/env node
// cli.mjs — the whole CLI
import { defineCommand, run } from 'burgee';

run(defineCommand({
  name: 'greet',
  description: 'Greet someone by name',
  options: { name: { type: 'string', required: true, description: 'who to greet' } },
  effects: 'read_only', // what running it does to the world; required, and what --mcp reads
  run: ({ options }) => ({ greeting: `hello, ${options.name}` }),
}));
```

```console
$ node cli.mjs --name ada
greeting: hello, ada

$ node cli.mjs --json --name ada
{"ok":true,"data":{"greeting":"hello, ada"},"meta":{"provenance":{"name":{"source":"flag","location":"--name"}}}}

$ node cli.mjs            # exit 2
error: missing required option --name
hint: pass --name <value>
usage: greet [options]
options:
  --name <value>  who to greet (required)
```

One file. No build step, no config file, no directory convention. A test enforces
that on every commit.

## One declaration, every surface

```text
defineCommand()  ──▶  manifest  ──┬──▶  human help
                                  ├──▶  --json      one stable envelope
                                  ├──▶  --schema    versioned, one document per surface
                                  ├──▶  --mcp       an MCP server, generated
                                  ├──▶  completions bash · zsh · fish · pwsh
                                  ├──▶  TypeScript types
                                  └──▶  docs + llms.txt
```

Nothing here needs keeping in sync, because nothing is written twice.

## What is in the box

| Import | Gives you |
| :-- | :-- |
| `burgee` | `defineCommand()`, `run()`, the exit-code contract and the JSON envelope. |
| `burgee/commander` | The commander API, graded by commander's suite. |
| `burgee/testing` | Run a command in-process and assert on its result — no spawning. |
| `burgee/brand` | One brand declaration → flag, favicon, OG card, cover, lockup. The logo above is its own output. |
| `burgee/plugin` | `definePlugin()`, `validate()`, `CONTRACT` and `PluginError` — the host, at the subpath every package in the family publishes its host at. |
| `burgee/program-schema.json` | The JSON Schema every `--schema` document validates against. |
| `burgee/locale-pack-schema.json` | The JSON Schema a locale pack is written against: every message id, with its English. |

## Writing a plugin

A plugin is one module whose default export is a plain object. In full, with a command and a
hook:

```js
// acme-plugin.mjs
export default {
  name: 'acme',
  contract: 1, // required on a plain object; `definePlugin` from `burgee/plugin` stamps it for you
  commands: [
    { path: ['audit'], description: 'Audit the tree', options: {}, effects: 'read_only', run: () => ({ findings: 0 }) },
  ],
  hooks: {
    // One hook per stage: parse, preRun, postRun, onError, shutdown. `filter.command` is a
    // RegExp tested against the command's path, words joined by spaces (`deploy prod`);
    // leave `filter` out and the hook fires for every command.
    preRun: { filter: { command: /^publish/ }, handler: (ctx) => {} },
  },
};
```

A plugin's command is read by exactly the code a first-party one is read by, so the same
refusals apply: reserved option names, duplicate flags, a contributed path that is already
declared — and `effects`, which every runnable command declares: `read_only`, `idempotent`,
`non_idempotent` or `withheld`. An object that reaches `use()` without a `contract` is refused
rather than accepted on trust, because burgee's extension point shipped before it validated
anything.

Check it before it ships. `--json` returns the report as a document, and the exit code is the
verdict:

```bash
npx burgee check ./acme-plugin.mjs --json
# in a clone of this repository, where dist/ is not committed: build burgee and the five
# packages it imports, then run the built bin
npx turbo run build --filter=burgee
node packages/burgee/dist/cli.js check ./acme-plugin.mjs --json
```

```json
{"ok":true,"data":{"name":"acme","commands":[{"path":"audit","description":"Audit the tree","effects":"read_only"}],"hooks":[{"stage":"preRun","applies":"commands matching /^publish/"}]},"meta":{"provenance":{}}}
```

`data.name` is the plugin, `data.commands` one row per contributed command, and `data.hooks`
one row per hook with its `stage`. A refusal exits 1 and carries `data.refused` instead —
`{ code, message, fix }`, where `fix` is the edit to make. `ok` agrees with the exit code, so
it is `false` here, and `data.refused.fix` says what to change:

```json
{"ok":false,"data":{"refused":{"code":"E_PLUGIN_CONTRACT","message":"plugin \"acme\" declares no contract; …","fix":"add `contract: 1` — `definePlugin` from `burgee/plugin` stamps it"},"exitCode":1},"meta":{"provenance":{}}}
```

## Speaking your user's language

Help, usage errors and hints can speak the user's language; `--json`, `--schema`, `--mcp`,
`--format=agent`, error kinds and exit codes never change with it, and a test in this package
fails if one does. A language is a plugin carrying `locales`, written against
[`burgee/locale-pack-schema.json`](https://github.com/ofri-peretz/burgee/blob/main/packages/burgee/src/locale-pack-schema.json), which lists every message
id with its English:

```js
// fr-pack.mjs
export default {
  name: 'fr',
  contract: 1,
  locales: {
    fr: {
      'usage.unknownOption': 'option inconnue {option}',
      'help.usage': 'Utilisation :',
      // A message with {count} takes the plural forms Intl.PluralRules selects for the locale.
      'usage.stdinOnce': { one: '…{count} argument…', many: '…{count} d’arguments…', other: '…{count} arguments…' },
    },
  },
};
```

Register it with `program.use(pack)`. The locale is the program's `locale` run option, then
`BURGEE_LOCALE`, then `LC_ALL`, `LC_MESSAGES` and `LANG`, so `LANG=fr_FR.UTF-8` finds `fr-FR`
and then `fr`. When an agent is detected, `LANG` is ignored, because an agent inherits it
without asking for it, and only the option or `BURGEE_LOCALE` applies. An id the pack leaves out
stays in English. `npx burgee check ./fr-pack.mjs --json` renders every message and gives each
locale's `coverage` (the ids translated, the ids left in English, and each plural message's forms
against the forms the locale selects), or refuses an unknown id, a placeholder the English lacks,
or a missing plural form. Your own text takes a
locale map, base language first, and help shows the user's language while `--schema` keeps the
base language:

```js
defineCommand({ name: 'deploy', description: { en: 'Deploy the site', fr: 'Déployer le site' }, effects: 'non_idempotent', run })
```

## Migrating

Already on commander or yargs? Change one import:

```diff
- import { Command } from 'commander';
+ import { Command } from 'burgee/commander';
```

```diff
- import yargs from 'yargs';
+ import yargs from 'burgee/yargs';
```

Your code and your tests are unchanged.

Or let the codemod make that change, and the same one for chalk, ora, string-width,
cross-spawn, signal-exit and every other import the family has a graded drop-in path for:

```bash
npx burgee migrate --dry-run
npx burgee migrate
```

It rewrites import specifiers and nothing else — the mocks in your tests included — for the
incumbents your `package.json` declares (`--only` and `--skip` change the choice). It leaves a
replacement that is not level yet alone with its grade, refuses a file it cannot rewrite whole,
moves an incumbent in every file or in none, and prints the install command to run next, each
family package pinned to the version that carries its drop-in. It exits 1 when anything was
refused, and the report's first line then says the run was `partial` and how many files moved —
[Migrate](https://burgee.interlace.tools/docs/migrate).

## Compatibility

Drop-in compatible with both incumbents, graded by **their own test suites** — 1,360 / 1,360
of commander's tests and 816 / 816 of yargs' on the
[compatibility page](https://burgee.interlace.tools/docs/compatibility) — with the pass rate
published and ratcheting. A façade is never called "compatible" until its host's own suite
passes 100%; below that the rate is published instead of claimed.

## Benchmarks

Every number here is produced by `npm run bench` and published at [burgee.interlace.tools/docs/benchmarks](https://burgee.interlace.tools/docs/benchmarks).

Graded by the incumbent's own test suite:

| suite | passing |
| :-- | --: |
| `commander` | 1360 / 1360 |
| `extra-typings` | 369 / 369 |
| `meow` | 146 / 148 |
| `yargs` | 816 / 816 |

## For agents

Every command answers the same declaration four more ways, with nothing written by hand:

- `--json` — one stable envelope, `{ ok, data, meta }`, with the provenance of every option.
- `--schema` — the whole command tree as data, versioned, one document per surface. It validates
  against `burgee/program-schema.json`, the JSON Schema the package publishes, so a CI job can pin
  a program's surface without writing its own idea of the shape.
- `--mcp` — the same manifest served as MCP tools over stdio; each tool's `effects` becomes its
  MCP hints, and `withheld` keeps a command out of the list.
- **Exit `2`** when the *command* was wrong, with a `hint:` — so an agent rewrites the command
  rather than retrying it.
- **A failure names the next step.** A `fix:` when there is exactly one (the flag or command it
  was nearest to), otherwise the failing command's usage line and options, or, for an unknown
  command, the commands that exist. It is prose on stderr, and `error.usage` in the `--json`
  envelope.
- `--explain <option>` — where a value came from: flag, env, config or default. Every
  command's help lists it, the root help ends with one line for agents, and `--schema` and the
  unknown-command hint name it too.
- **`-q`/`--quiet` silences decoration, never data or a failure.** Hand `ctx.runtime` to what
  draws, and a caique spinner, `log.info` or `note` writes nothing; `log.error` still writes,
  and a prompt still asks:

  ```ts
  import { spinner } from 'caique/clack';

  const spin = spinner({ runtime: ctx.runtime }); // silent under --quiet
  ```
- **A plugin can be checked before it ships.** `npx burgee check ./plugin.mjs --json` returns
  `{ name, commands, hooks }` as `data`, or `data.refused` with a `fix` and exit 1 — the whole
  plugin and both documents are under [Writing a plugin](#writing-a-plugin).

[Your CLI is an agent tool](https://burgee.interlace.tools/docs/agent-surfaces) has each
surface; the docs themselves are at
[burgee.interlace.tools/llms.txt](https://burgee.interlace.tools/llms.txt) and
[llms-full.txt](https://burgee.interlace.tools/llms-full.txt).

## Status

`burgee` is published and working: the engine, the exit-code contract, the JSON envelope,
help from the manifest, plugins with hook filters, and a `burgee/commander` façade that
runs a real commander program. The dev loop, prompts, lazy commands and groups are not
here yet.

Roadmap, architecture and the 114-requirement floor:
<https://github.com/ofri-peretz/burgee>

## FAQ

### Is burgee a commander alternative?

Yes — and a yargs alternative. It is drop-in compatible with both: change
`import { Command } from 'commander'` to `import { Command } from 'burgee/commander'` (or
`yargs` to `burgee/yargs`) and your code and tests are unchanged. Compatibility is graded by
each host's own test suite in CI, not asserted. The guides:
[Switching from commander](https://burgee.interlace.tools/docs/vs/commander) and
[Switching from yargs](https://burgee.interlace.tools/docs/vs/yargs).

### How do I make my CLI usable by an AI agent?

Declare it with `defineCommand()` — or keep it on commander or yargs syntax through the
drop-in front ends. Every command then answers `--json` with one stable envelope,
`--schema` with the whole command tree as data, and exits `2` when the *command* was wrong
so an agent knows to rewrite it rather than retry. None of it is written by hand; it is
the declaration read by a different reader.
[Your CLI is an agent tool](https://burgee.interlace.tools/docs/agent-surfaces) has each surface.

### How do I expose a CLI over MCP?

Run it with `--mcp`: the same manifest is served as MCP tools over stdio. Every runnable
command declares its `effects` — `read_only`, `idempotent` or `non_idempotent`, which become
MCP's hints, or `withheld`, which keeps it out of the tool list — so nothing reaches an
agent by accident. On `burgee/commander` and `burgee/yargs`, a command that declared
nothing is still listed, marked `effects: 'undeclared'`. Register it with any stdio client:

```json
{ "mcpServers": { "mytool": { "command": "npx", "args": ["mytool", "--mcp"] } } }
```

### Does it have dependencies?

None outside the burgee family. `burgee` installs five packages from that family —
`bellpull`, `closeout`, `linegauge`, `roundel` and `seniority` — and each of those takes
nothing from outside it either: one repository, one release pipeline, one supply chain to
audit.

## API

The entry points are under [What is in the box](#what-is-in-the-box); the reference, with every
option and type, is at [burgee.interlace.tools](https://burgee.interlace.tools/docs/packages/burgee).

## Where it sits

Plugins register under the `commands`, `hooks`, `locales` keys, against the one schema the whole family shares.

Nothing in this family builds on it yet, and it builds on `bellpull`, `closeout`, `linegauge`, `roundel`, `seniority`.

## The family

Ten packages, one repository, one release pipeline. Each installs and works on its own, and each
owns one job. Six of them — `bellpull`, `closeout`, `linegauge`, `paratext`, `roundel`, `seniority`
— depend on nothing; the others depend only on packages in this table, and every dependency points
one way, down the [layers](https://burgee.interlace.tools/docs/concepts/family).

No package declares a dependency from outside the family; `react` and `react-reconciler` are
optional peers of `controlroom`, which npm does not install.
[`package-shape-lock`](https://github.com/ofri-peretz/burgee/blob/main/scripts/package-shape-lock.test.ts)
holds that for every manifest, and
[`independence-install-lock`](https://github.com/ofri-peretz/burgee/blob/main/scripts/independence-install-lock.test.ts)
installs each package alone and finds nothing but the family packages it declares.

Releases are published by one workflow through npm trusted publishing: no npm token is used, and
each release carries SLSA provenance, which `npm view <package> dist.attestations` shows.
[`trusted-publishing-lock`](https://github.com/ofri-peretz/burgee/blob/main/scripts/trusted-publishing-lock.test.ts)
keeps both true.

| Package | What it is | Migrates from |
| :-- | :-- | :-- |
| **burgee** (this package) | The CLI framework: one declaration, every surface | commander, yargs and meow |
| [roundel](https://roundel.interlace.tools/docs) | Colour: one output policy, semantic tokens, a theme | chalk, picocolors, supports-color and yoctocolors |
| [flagstaff](https://flagstaff.interlace.tools/docs) | The frame loop: spinners, progress, boxes and tables | ora, log-update, boxen and cli-table3 |
| [caique](https://caique.interlace.tools/docs) | Prompts that are flags first, and never hang | @inquirer/core |
| [linegauge](https://linegauge.interlace.tools/docs) | Measuring, wrapping, truncating and slicing styled text | string-width, wrap-ansi, strip-ansi, slice-ansi, cli-truncate and widest-line |
| [paratext](https://paratext.interlace.tools/docs) | Hyperlinks, images, title, clipboard and notifications | ansi-escapes, terminal-link and term-img |
| [seniority](https://seniority.interlace.tools/docs) | Configuration precedence and discovery, with provenance | cosmiconfig, lilconfig, dotenv and rc |
| [closeout](https://closeout.interlace.tools/docs) | Exit handlers, terminal restore and a bounded shutdown | signal-exit, exit-hook, restore-cursor, cli-cursor and onetime |
| [bellpull](https://bellpull.interlace.tools/docs) | Subprocesses, and which executable actually ran | cross-spawn and which |
| [controlroom](https://controlroom.interlace.tools/docs) | Keyboard-driven terminal screens, inline or full-screen | ink |

Every migration guide, and the family-wide [compatibility](https://burgee.interlace.tools/docs/compatibility)
and [benchmarks](https://burgee.interlace.tools/docs/benchmarks) pages, are on
[burgee.interlace.tools](https://burgee.interlace.tools/docs/packages).

## Contributing

Issues and pull requests are welcome at [ofri-peretz/burgee](https://github.com/ofri-peretz/burgee/issues); read
[CONTRIBUTING.md](https://github.com/ofri-peretz/burgee/blob/main/CONTRIBUTING.md) first. Report a vulnerability privately, as
[SECURITY.md](https://github.com/ofri-peretz/burgee/blob/main/SECURITY.md) describes — never in a public issue.

## Licence

MIT © Ofri Peretz — see [LICENSE](https://github.com/ofri-peretz/burgee/blob/main/packages/burgee/LICENSE).

---

# Packages

> burgee and the 9 packages it is built from: what each migrates from, and the site its docs live on.

Source: https://burgee.interlace.tools/docs/packages

Every package in the family is published on its own, depends on nothing outside this
repository, and has a site of its own, or a section here until its site exists. Its page
is its README, projected; the family-wide pages — [compatibility](/docs/compatibility),
[comparison](/docs/comparison) and [gallery](/docs/gallery) — stay here, one copy each.

| Package | Migrates from | Site |
| :-- | :-- | :-- |
| [burgee](https://burgee.interlace.tools/docs/packages/burgee) | commander, yargs and meow | [burgee.interlace.tools](https://burgee.interlace.tools) |
| [bellpull](https://bellpull.interlace.tools/docs) | cross-spawn and which | [bellpull.interlace.tools](https://bellpull.interlace.tools) |
| [caique](https://caique.interlace.tools/docs) | @inquirer/core | [caique.interlace.tools](https://caique.interlace.tools) |
| [closeout](https://closeout.interlace.tools/docs) | signal-exit, exit-hook, restore-cursor, cli-cursor and onetime | [closeout.interlace.tools](https://closeout.interlace.tools) |
| [controlroom](https://controlroom.interlace.tools/docs) | ink | [controlroom.interlace.tools](https://controlroom.interlace.tools) |
| [flagstaff](https://flagstaff.interlace.tools/docs) | ora, log-update, boxen and cli-table3 | [flagstaff.interlace.tools](https://flagstaff.interlace.tools) |
| [linegauge](https://linegauge.interlace.tools/docs) | string-width, wrap-ansi, strip-ansi, slice-ansi, cli-truncate and widest-line | [linegauge.interlace.tools](https://linegauge.interlace.tools) |
| [paratext](https://paratext.interlace.tools/docs) | ansi-escapes, terminal-link and term-img | [paratext.interlace.tools](https://paratext.interlace.tools) |
| [roundel](https://roundel.interlace.tools/docs) | chalk, picocolors, supports-color and yoctocolors | [roundel.interlace.tools](https://roundel.interlace.tools) |
| [seniority](https://seniority.interlace.tools/docs) | cosmiconfig, lilconfig, dotenv and rc | [seniority.interlace.tools](https://seniority.interlace.tools) |

## Which one do I need?

Two packages draw in a terminal. They split on whether the program owns the screen.

- **flagstaff, for inline output in a scrolling terminal.** Spinners, progress, task lists,
  boxes and tables, drawn in place under what the program has already printed and left in
  the scrollback as ordinary lines. It reads no keys. Usable today, with drop-in paths for
  ora, log-update, boxen and cli-table3.
- **controlroom, for a screen that reads keys.** Panes, tabs with key hints, focus and
  collapse, an input line, with keys routed to the program, either inline under the
  program's output or in the alternate screen. An ink program moves by its import, to
  `controlroom/ink`. Coming from blessed, neo-blessed or terminal-kit? The
  [coming-from guides](/docs/coming-from/blessed) map each one onto `open()`, and
  `burgee migrate` reports their sites.

If a program only draws, it is flagstaff, even when the drawing is busy. If it reads keys
while it draws, it is controlroom, and its inline screen keeps that in the main screen,
the shape of a chat CLI. A question asked once, such as a confirm or a pick, is neither:
it is a prompt, and prompts are caique's.

Off a terminal, flagstaff gives a pipe, CI, a screen reader and `--json` each component's
static projection, never a redraw, and controlroom does the same for a whole screen.

---

# Plugins

> Every layer takes plugins the same way — a plain object, validated against one published schema, checked by the package's own command before it ships. One object can extend all nine.

Source: https://burgee.interlace.tools/docs/plugins

Generated by `npm run plugins:page` from the packages themselves. Do not edit by hand.

Every package in the family takes plugins, and all 10 take them the same way. A plugin
is a plain object. Each package validates it against **one published schema** — the same
`schema.json` ships in every package — and each package has a `check` command that shows what
a plugin contributes, or refuses it with a code and the fix, before it ships.

Each package reads its own key and ignores the others, so **one object can extend any subset
of the family that is installed**, including all of it.

## One object, 10 layers

A company's CLI conventions, in one file: brand colours, a spinner, a terminal quirk, a
terminal capability, a config source, where its tools live, what to flush on exit, a prompt
of its own, and a command every one of its CLIs gets.

```js title="examples/plugins/acme.mjs"
// One plugin object, nine layers. A company's CLI conventions in a single file: brand
// colours, a spinner, a terminal quirk, a config source, where its tools live, what to
// flush on exit, a prompt of its own, a terminal capability and a command every CLI
// gets. Each package reads its own key and ignores the rest, so the same object
// registers into any subset of the family that is installed.
//
// Check it against any layer: `npx roundel check examples/plugins/acme.mjs`, and the
// same for flagstaff, linegauge, paratext, seniority, bellpull, closeout, caique and
// `npx burgee check`. `scripts/plugin-example-lock.test.ts` runs all nine.
export default {
  name: 'acme',
  contract: 1,

  // roundel — the brand, as semantic tokens every styled line reads.
  tokens: { ok: '#1a7f37', error: '#cf222e', hint: '#0969da' },

  // flagstaff — a spinner, with the line a pipe or an agent prints instead.
  spinners: { acme: { frames: ['◐', '◓', '◑', '◒'], interval: 100, static: '◐' } },

  // linegauge — the Nerd Font glyphs this company's prompt draws two columns wide.
  widths: { powerline: { ranges: [[0xe0a0, 0xe0a3], [0xe0b0, 0xe0b3]], columns: 2, why: 'Nerd Font powerline glyphs render wide in the company terminal profile' } },

  // paratext — a terminal capability, with what prints when the terminal lacks it.
  capabilities: { beep: { name: 'beep', osc: 'BEL', when: { tty: true }, encode: '\u0007', fallback: '' } },

  // seniority — a config layer between the flag (0) and the declared default (40).
  sources: { vault: { rank: 25, read: () => undefined, location: 'vault://acme/cli' } },

  // bellpull — where the company's pinned toolchain lives, searched before PATH.
  resolvers: { asdf: { rank: -10, paths: ['{ASDF_DATA_DIR}/shims'], when: { envAny: ['ASDF_DATA_DIR'] } } },

  // closeout — flush telemetry before the process exits, whatever ended it.
  handlers: [{ name: 'flush-telemetry', phase: 'flush', run() {} }],

  // caique — a prompt kind of the company's own, with its non-interactive projection.
  widgets: { rating: { static: () => 'rate 1-5', sample: { running: {}, done: {} } } },

  // burgee — a command every company CLI gets, declared exactly as a program's own.
  commands: [{ path: ['doctor'], description: 'Check this machine against the company toolchain', options: {}, effects: 'read_only', run: () => ({ ok: true }) }],
};
```

This is a committed file, not an illustration: `scripts/plugin-example-lock.test.ts` runs
9 `check` commands and flagstaff's validator against it, and the published
schema over it, on every CI run.

## What each layer takes

| Package | Key | What a plugin contributes | Check it | What the incumbent offers |
| :--- | :--- | :--- | :--- | :--- |
| **bellpull** | `resolvers` | bellpull resolvers by name: extra directories searched for an executable, before PATH (negative rank) or after it (positive). Two resolvers with one name shadow; two names both apply, in rank order. | `npx bellpull check ./plugin.mjs` | **cross-spawn** — None<br />**which** — None |
| **burgee** | `commands` | burgee commands this plugin contributes. Each is read by exactly the code a program's own command is, and a burgee plugin must declare `contract`. | `npx burgee check ./plugin.mjs` | **commander** — Lifecycle hooks on one program (`.hook('preAction')`); no plugin shareable across programs — the plugin RFC, [#2505](https://github.com/tj/commander.js/issues/2505), is open<br />**extra-typings** — commander's, unchanged: its JavaScript is commander's, and what it adds is types<br />**yargs** — Middleware on one program (`.middleware()`), and commands loaded from modules (`.commandDir()`)<br />**meow** — None<br />**cac** — Events on one program (`cli.on()`)<br />**citty** — `setup` and `cleanup` on each command |
|  | `hooks` | burgee lifecycle hooks. parse rewrites argv before a command is resolved; preRun opens around a command, and exactly one of postRun or onError closes; shutdown fires once as the program leaves, by any path. |  |  |
|  | `locales` | burgee locale packs (localised-human-surfaces R4): a BCP 47 language tag, as Intl.Locale writes it, mapped to catalog ids and their translations. A message is a string, or for a message whose English carries a count placeholder, one string per plural form Intl.PluralRules selects for the locale. burgee/locale-pack-schema.json lists every id with its English; `burgee check` renders a pack or refuses it. |  |  |
| **caique** | `widgets` | caique prompt widgets by kind. The six built-in kinds — text, confirm, select, multiselect, password, path — cannot be replaced: a plugin adds kinds of its own. | `npx caique check ./plugin.mjs` | **clack** — Custom prompts built on `@clack/core`<br />**inquirer-prompts** — A `theme` per prompt; new prompts are built on `@inquirer/core`'s `createPrompt`<br />**inquirer-core** — Custom prompts built with `createPrompt` |
|  | `locales` | burgee locale packs (localised-human-surfaces R4): a BCP 47 language tag, as Intl.Locale writes it, mapped to catalog ids and their translations. A message is a string, or for a message whose English carries a count placeholder, one string per plural form Intl.PluralRules selects for the locale. burgee/locale-pack-schema.json lists every id with its English; `burgee check` renders a pack or refuses it. |  |  |
| **closeout** | `handlers` | closeout exit handlers. The phase decides the order they run in, not their position in this list. | `npx closeout check ./plugin.mjs` | **restore-cursor** — None<br />**exit-hook** — None — it is the hook<br />**signal-exit** — None — it is the hook<br />**onetime** — None<br />**cli-cursor** — None — the stream is an argument, per call |
| **controlroom** | `keymaps` | controlroom keymaps by name: key spec to action name, and the label each action shows in the hint line. `default` replaces the built-in keymap. | `npx controlroom check ./plugin.mjs` | **ink** — Components are the extension: any React component renders (`@inkjs/ui`, `ink-spinner`); no registry, no theme<br />**inkjs-ui** — A theme object passed to `ThemeProvider`, per tree (`extendTheme`) |
|  | `panes` | controlroom panes by name: the flagstaff component that draws each one, and its label. A tab bar is a pane over flagstaff's `tab-bar`. |  |  |
| **flagstaff** | `tokens` | A roundel theme: semantic token name to a hex colour, contrast-checked when flown. | `npx flagstaff check ./plugin.mjs` | **ora** — A custom spinner object, per instance (`spinner: { frames, interval }`)<br />**log-update** — None<br />**boxen** — A custom border object, per call (`borderStyle`)<br />**cli-table3** — Custom border characters, per table (`chars`) |
|  | `glyphs` | Symbols by meaning: `ok`, `fail`, `warn`, `info`, `running`. A plugin that ships glyphs changes every built-in that draws one. |  |  |
|  | `spinners` | Spinner styles by name, in cli-spinners' shape plus the static projection. |  |  |
|  | `borders` | Border styles a box can be drawn with, by name. |  |  |
|  | `components` | Components by name: `static(state)` returns the text a pipe, an agent or a screen reader gets; `frame(t, state)` is the optional animated form. |  |  |
| **linegauge** | `widths` | linegauge width overrides by name — the measurement section of a plugin, read the way flagstaff reads `spinners`. | `npx linegauge check ./plugin.mjs` | **string-width** — An option per call (`ambiguousIsNarrow`); no per-code-point override<br />**strip-ansi** — None<br />**wrap-ansi** — Options per call<br />**slice-ansi** — None<br />**cli-truncate** — Options per call<br />**widest-line** — None |
| **paratext** | `capabilities` | paratext capabilities by name — the OSC section of a plugin, read the way flagstaff reads `spinners`. | `npx paratext check ./plugin.mjs` | **ansi-escapes** — None<br />**terminal-link** — A `fallback` function, per call<br />**term-img** — A `fallback` function, per call |
| **roundel** | `tokens` | A roundel theme: semantic token name to a hex colour, contrast-checked when flown. | `npx roundel check ./plugin.mjs` | **chalk** — None — styles are code; there is no theme to register<br />**picocolors** — None — `createColors(enabled)` per instance, and nothing to register<br />**supports-color** — Options per call (`createSupportsColor(stream, { sniffFlags })`); nothing to register<br />**yoctocolors** — None — 61 plain functions, and nothing to register |
| **seniority** | `sources` | seniority configuration sources by name, ranked against the built-in layers: a flag is 0 and a declared default is 40, and a plugin source sits strictly between. | `npx seniority check ./plugin.mjs` | **rc** — A custom `parse` function, per call<br />**cosmiconfig** — Custom `loaders` per file extension and `searchPlaces`, per explorer<br />**lilconfig** — Custom `loaders` per file extension, per call<br />**dotenv** — None<br />**find-up** — A matcher function, per call, in place of a name |

The schema for every key above ships as `<package>/schema.json`. An editor, a validator or a
model can read it without running anything.

## What a plugin cannot do yet

- **burgee's hooks stop at help and config.** A plugin can act at
  `parse`, `preRun`, `postRun`, `onError`, `shutdown` — rewriting argv before a command is resolved,
  around the run, and once as the program leaves — but not inside help rendering and not in
  config resolution. Contributing commands has no such limit.
- **flagstaff's built-in components are not contributions.** A plugin adds spinners, borders
  and components of its own; it cannot replace `progress`, `box` or `table`.
- **The schema cannot say "function".** `static`, `run`, `read` and `handler` are required
  and described; that each is a function is checked by the package, not by the schema.
- **Whether a model writes a working plugin in one turn is unmeasured.** Each package has an
  eval case that asks exactly that, proven to tell a working plugin from a broken one; none
  has run against a model yet.

---

# Research

> What 329 open issues across yargs, commander, oclif, citty and clack say about the layer nobody owns.

Source: https://burgee.interlace.tools/docs/research

Snapshot taken 2026-09-05 with `npm run research:refresh`. Raw JSON in
[`.sdlc/research/issues/`](https://github.com/ofri-peretz/burgee/tree/main/.sdlc/research/issues). Every claim below cites an issue number so it can be re-read.

| Repo | Open | Read |
| :--- | ---: | :--- |
| yargs/yargs | 199 | all |
| tj/commander.js | 6 | all |
| oclif/core | 14 | all |
| oclif/oclif | 10 | all |
| unjs/citty | 40 | all |
| bombshell-dev/clack | 60 | all |

The one-line finding: **almost nothing in these trackers is about parsing argv.**
It is about everything that sits on top of parsing — help rendering, config
precedence, validation relationships, completions, error lifecycle, prompts,
machine-readability. That is the layer nobody owns, and it is the layer an AI agent
touches on every call.

---

## 1. Machine-readability and agent environments (the thesis, in their words)

The newest and most-discussed issues across all six repos converge on one need:
a CLI that a program, not a person, can drive.

- **clack #533** (2026-05, 9 comments) *Resumable prompts for agent environments*:
  "Interactive CLIs … break down in non-TTY environments like CI, and increasingly,
  AI coding agents. The CLI usually hangs forever and just fails."
- **citty #187** *Pluggable Logger*: wants to call a command programmatically and
  "get the output (to feedback to LLM)".
- **citty #117** *return usage as data instead of just a string*; **citty #94**
  `transformCommandToApi`; **yargs #2121** "have yargs introspect the CLI and
  provide command metadata"; **yargs #1005** "no way to list all the possible
  commands" (a 250-command CLI); **clack #525** automated help/man generation.
- **yargs #1605** invoke a command programmatically; **yargs #1838** API to check if
  a command string is known.
- **yargs #1334** track which arguments were defaulted; **oclif/core #854** "hard to
  tell whether a user really typed that flag or is just a default"; **oclif/core
  #1639** `dependsOn` satisfied by a flag's own default. Three trackers, one missing
  concept: *value provenance*.
- **yargs #1519** `--help` exits before stdout is flushed; **yargs #2118** a thrown
  error truncates stdout/stderr. Output integrity, which a human tolerates and a
  parser does not.
- **yargs #2394** help is printed when an async handler *fails*. For an agent this
  is the worst possible signal: a runtime failure that looks like a usage mistake.
- **commander #2549** pass a custom `env` instead of `process.env`; **yargs #2450**
  `getHelp(args)` for tests. Testability of the whole surface, not just the parser.
- **clack #286** use `isTTY` rather than `isCI` to decide what to render;
  **clack #585** *accessible mode*: spinners and live-redrawn prompts are
  re-announced on every repaint by screen readers. An agent reading captured stdout
  has exactly the screen reader's problem (**clack #510**: `\r` progress output
  captured as hundreds of lines).

## 2. Help and usage rendering — the largest single cluster (yargs)

The top yargs issue by reactions, and roughly a fifth of its tracker:

- **#684** (34 reactions, since 2016) group commands under headings.
- **#969** hide `[boolean]` type hints; **#427** customise "extra" help;
  **#1964** scriptname repeated before every command; **#877 / #1640** examples on
  one copy-pasteable line, multi-line examples; **#2003** width hard-coded to 80;
  **#2228** no separation between columns; **#2120 / #2000** `usage()` strips
  leading spaces; **#1181** command options before global options; **#1408 / #1349**
  documenting choices and array defaults; **#833** value placeholder in help;
  **#1699** ANSI colour in a command name breaks matching; **#1500 / #1331 / #1025**
  subcommand help, examples and options missing; **#1020** `cmd help <sub>`;
  **#2248** deprecated flag not shown in help; **#2012** positional defaults absent
  from help; **#1265** short vs long descriptions by context; **#1680** epilogue
  only on root; **#2094** localised descriptions.
- **oclif/core #1001 / #1002** show min/max, `dependsOn`, `exclusive` in help.
- **citty #137** customise each part of `showUsage`; **yargs #1935 / #1681**
  document environment variables in help.

Reading: help is data being rendered by a renderer nobody can replace. Own the
renderer, derive help from a schema, and every one of these becomes a template
change — and `--help --json` falls out for free.

## 3. Config and environment precedence

- **yargs #873** (22 comments) env vars trigger strict-mode errors for unrelated
  commands; **#821** array from env; **#856** any arg via env; **#1655** explicit env
  var names per option; **#2501** `--no-` variants via env; **#2005** env names
  camel-cased unexpectedly; **#858 / #1782 / #2472 / #1858** config files for
  subcommands, nested keys, strict mode; **#1305 / #1627** dot-notation and deep
  merge; **#2234** async config loader; **#1363 / #1135** `extends` merge and
  resolution; **#1676** `--no-config` still loads; **#2191** `pkgConf` only once;
  **#1234** load a user config if it exists.
- **yargs #2400 / #1934**, **commander #2346**, **citty #200** — reading
  `name`/`version` from the right `package.json` (monorepos, global installs).
- **oclif/core #1075** native `.env` support.

Reading: a precedence layer (flags > env > config > defaults) with provenance is a
recurring, unowned need. It is the same concept as the "was this defaulted" issue in
section 1.

## 4. Validation and option relationships

- **yargs #1093 / #439** exactly-one-of, required group; **#1322 / #898 / #1190**
  `implies` as a function, with `--no-`, with nested keys; **#793** dynamic choices
  depending on another arg; **#1379** `coerce` fights `choices`; **#1079** invalid
  number becomes `NaN`; **#1188** a `file` type; **#890** an `object` type;
  **#1532** a true flag (`nargs: 0`); **#1318 / #2011 / #846 / #1530 / #1336**
  array semantics; **#1186** validation order (`exclusive` before `choices`);
  **#1198** invalid `type` accepted silently; **#887** duplicate aliases shadow
  silently; **#933** `-output` parses as `-o utput`.
- **Reserved names**: **yargs #1323 / #1864 / #2199 / #2064** an option called
  `version` fails silently — "I wasted nearly an hour."
- **citty #84 / #103 / #138** validator, normaliser, `number` type; **clack #597**
  validators that throw.

Reading: schema-first (Standard Schema) with typed relationships. Reserved-name
collisions and silent-coercion are lint rules, not runtime features.

## 5. TypeScript

**yargs #1649 / #1679 / #1751 / #2292 / #1392 / #2437 / #2137 / #2360 / #2401 / #2487 / #1940**; **citty #244**; **clack #234 / #131 / #178**. camelCase in code vs
kebab-case in help, positional typing, variadic typing, defaults typed as functions,
group inference. All are consequences of types not being *derived* from one schema.

## 6. Completions

**yargs #1904** fish (20 reactions), **#1290 / #1210** PowerShell with metadata,
**#1684** static completions because dynamic ones are slow, **#2131 / #2126** Fig,
**#2402** zsh autoload file, **#2390** dynamic values, **#1702** completion as an
option not a command, **#2254** `--no-x` not completed, **#1965** pressing TAB *runs
the command*, **#831 / #2298** per-command and pluggable completion, **#2300** hard
to debug, **#1133 / #1192 / #1277 / #1886** correctness bugs; **citty #217 / #168 / #59**. Reading: generate static completions from the manifest for four shells.

## 7. Error lifecycle and exit behaviour

**yargs #1069** (24 comments) parse callback fires before the handler promise
settles; **#1399** throw inside `coerce` does not terminate; **#1975** failing
`check()` does not stop the handler; **#1797** `fail()` misses sync errors;
**#2133** `fail()` gets no argv; **#2223 / #1828** middleware runs twice, skips
camel-casing; **#1983** `fail(false)` throws; **citty #112** error bubbling;
**clack #573 / #408**, **oclif/oclif #958** Ctrl+C handling and raw-mode leaks.
Reading: an explicit lifecycle (parse → validate → run → render → exit) with a
single error envelope and a flush-before-exit guarantee.

## 8. Modularity for large CLIs

**yargs #684** groups, **#1005** 250 commands, **#1067 / #2479 / #2267 / #1269**
`commandDir` and ESM, **#2115 / #2246** deprecate a command, **#2107** alias to
canonical name, **#1755** share options across commands; **commander #2505** plugin
API RFC, **#2583** shared command configuration helper; **citty #154 / #151 / #93**
shared args, user-extendable commands, hidden commands; **oclif/core #984** aliases
on subcommands. Reading: a command *manifest* — oclif's actual moat — from which
docs, completions, help and agent tool definitions are all generated.

## 9. Interactive prompts

**clack #533** agent environments, **#22** hooks, **#83** cancellation API, **#39**
go back a step, **#167** override a prompt with a flag, **#379** global settings,
**#345** style representation; **oclif/oclif #1492** auto-prompt for missing flags.
Reading: every prompt must have a flag equivalent, and in a non-TTY the prompt becomes
an error that names the flag.

## 10. Parsing edge cases (the only cluster we do NOT re-implement)

**yargs #1312** single dash for stdin (17 reactions), **#1076 / #1046 / #1189 / #1158 / #2481 / #2196** strict-mode gaps, **#1324 / #2416** quotes eaten, **#1527**
`--` handling, **#1821 / #2423** pass-through after a positional (`docker run` style),
**#1074**; **commander #2530** `--` not preserved for executable subcommands,
**#2603** Electron argv; **citty #41 / #253** positional equal to a subcommand name,
**#237** `-foo=bar`, **#201** warn on unknown options. Reading: commander already
gets most of these right and fixes the rest in weeks. Wrap it; do not fork it.

## 11. Runtime and packaging

**oclif/core #1627** (2026-07): "ships 17 runtime dependencies, several of which now
have first-class native equivalents (`util.styleText`, `fs.glob`, global `fetch`,
`process.stdout.isTTY`)"; **#1450 / #1396** CJS-only deps, Node 18; **oclif/oclif #968 / #1624 / #1219 / #2024 / #1985** Deno, bun, pnpm, ESM; **yargs #2004 / #2068 / #2101 / #2186 / #2216** bundling, browser, Deno; **citty #6** build preset;
**clack #202** Deno. Reading: zero runtime dependencies beyond commander, ESM-only,
Node 24 natives. `util.styleText` makes a chalk dependency unnecessary.

## 12. Two signals about maintainers

- **oclif/core #1644** (2026-09): "`eslint --fix` corrupts source … because lint rules
  conflict with the repo's actual TS setup." A CLI framework's own lint setup fighting
  itself. This is the adoption wedge for Interlace's plugins in CLI repos.
- **yargs #2488** trusted publishing, **#2070** how to sponsor, **#1465** coverage.
  yargs is maintained, but by goodwill; its tracker is a backlog of *layer* features
  it has decided not to own.

---

# Supply chain and continuity

> What installing each burgee package puts on disk, how releases are published and signed, the licence, and what a fork inherits. Every statement links the check that holds it.

Source: https://burgee.interlace.tools/docs/supply-chain

This page states what the burgee family installs, how it is published, and what a team that
forks it keeps. Each statement links the check that holds it in CI. Where a check is missing,
the statement is not on this page.

## What an install brings in

Installing any burgee package installs that package and the burgee packages it depends on,
and nothing else. Each package below was installed alone into an empty directory, offline, from
the tarballs `npm pack` builds from this repository, and its tree listed with
`npm ls --all --parseable`.

{/* install-graph:start */}

| `npm install` | Packages installed | Which |
| :--- | ---: | :--- |
| `bellpull` | 1 | `bellpull` |
| `burgee` | 6 | `bellpull`, `burgee`, `closeout`, `linegauge`, `roundel`, `seniority` |
| `caique` | 6 | `bellpull`, `caique`, `closeout`, `linegauge`, `paratext`, `roundel` |
| `closeout` | 1 | `closeout` |
| `controlroom` | 8 | `bellpull`, `caique`, `closeout`, `controlroom`, `flagstaff`, `linegauge`, `paratext`, `roundel` |
| `flagstaff` | 5 | `closeout`, `flagstaff`, `linegauge`, `paratext`, `roundel` |
| `linegauge` | 1 | `linegauge` |
| `paratext` | 1 | `paratext` |
| `roundel` | 1 | `roundel` |
| `seniority` | 1 | `seniority` |

Generated by `npm run install-graph` from an offline install of each package alone, from the tarballs `npm pack` builds; do not edit by hand.

{/* install-graph:end */}

- **Every installed package is a burgee package.** The one exception the check allows is an
  optional peer a family package declares: `controlroom/ink` renders through the program's own
  `react` and `react-reconciler`, which npm does not install unless the program asks for them.
  Held by
  [`install-graph-lock`](https://github.com/ofri-peretz/burgee/blob/main/scripts/install-graph-lock.test.ts),
  which also requires the table above to equal a fresh measurement.
- **Nothing runs at install time.** No installed package declares a `preinstall`, `install` or
  `postinstall` script, or ships a `binding.gyp`, which npm would build without a script asking
  it to. Held by the same lock, reading the manifests as they land in `node_modules`.
- **Each package loads alone.** Every entry in each package's `exports` map is imported from
  that install, and no import reaches a package it does not declare. Held by
  [`independence-install-lock`](https://github.com/ofri-peretz/burgee/blob/main/scripts/independence-install-lock.test.ts).
- **The dependency counts in the READMEs match the manifests.** Held by
  [`dependency-claim-lock`](https://github.com/ofri-peretz/burgee/blob/main/scripts/dependency-claim-lock.test.ts).
  The direction of every edge is on [The family](/docs/concepts/family).

burgee parses argv with Node's own `util.parseArgs`, so the tokeniser a program depends on
ships with Node rather than with a package.

## How a release is published

- **Trusted publishing, with no npm token.** Every package is published from the
  [`release.yml`](https://github.com/ofri-peretz/burgee/blob/main/.github/workflows/release.yml)
  workflow through npm trusted publishing (OIDC). No workflow names an npm token, and the publish
  job reads no secret but `GITHUB_TOKEN`. Held by
  [`trusted-publishing-lock`](https://github.com/ofri-peretz/burgee/blob/main/scripts/trusted-publishing-lock.test.ts).
- **SLSA provenance on every version.** The publish runs with `--provenance`, held by the same
  lock. To verify a version yourself, run `npm view burgee dist.attestations` for the registry's
  attestation, or `npm audit signatures` in a project that installs it.
- **An SBOM on every GitHub Release.** The release workflow attaches a CycloneDX SBOM of what
  installing the package brings in, from the lockfile with development, optional and peer
  dependencies left out. Held by the same lock. Attaching it is a separate step after the
  publish: if it fails, the release workflow logs a warning and the npm publish stands.

## Security posture

- **Reporting.** [SECURITY.md](https://github.com/ofri-peretz/burgee/blob/main/SECURITY.md)
  says how to report a vulnerability privately and which versions are supported. Its supported
  versions are read against the manifests by
  [`stable-status-lock`](https://github.com/ofri-peretz/burgee/blob/main/scripts/stable-status-lock.test.ts).
- **OpenSSF Scorecard.** [Scorecard](https://scorecard.dev/viewer/?uri=github.com/ofri-peretz/burgee)
  runs weekly from
  [`scorecard.yml`](https://github.com/ofri-peretz/burgee/blob/main/.github/workflows/scorecard.yml).
  It scored this repository 7.1 of 10 on 2026-10-10; the badge on the README is the live
  figure. Four checks scored 0: Maintained, Code-Review and CII-Best-Practices, which
  SECURITY.md explains no file in the repository can close, and Contributors. Vulnerabilities
  scored 1 of 10. It reads the repository's lockfile, which holds the development tooling; the
  table above is what an adopter installs. The same question is now asked daily, and on every
  pull request that changes the lockfile or a manifest, by
  [`check:osv`](https://github.com/ofri-peretz/burgee/blob/main/scripts/osv-check.ts), which
  queries OSV for every locked package. One advisory with no fixed release, in a development
  tool, is waived until 2026-11-30, and
  [the decision](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/decisions/D-20261011-osv-lockfile-zero.md)
  says why.

## Licence and continuity

- **MIT, every package.** The repository is under the
  [MIT licence](https://github.com/ofri-peretz/burgee/blob/main/LICENSE), and every installed
  package's manifest declares `MIT`, held by
  [`install-graph-lock`](https://github.com/ofri-peretz/burgee/blob/main/scripts/install-graph-lock.test.ts).
- **One repository.** All ten packages are built, tested and released from
  [one repository](https://github.com/ofri-peretz/burgee) through one release workflow, so a
  fork of that repository is a fork of the whole family.
- **A fork keeps its conformance tests.** Each incumbent's own test suite is vendored under
  [`packages/compat-oracle/vendor`](https://github.com/ofri-peretz/burgee/tree/main/packages/compat-oracle/vendor)
  and run in CI against the drop-in path by
  [`compat.yml`](https://github.com/ofri-peretz/burgee/blob/main/.github/workflows/compat.yml),
  which fails below the committed baseline. A fork inherits those suites and that gate, so a
  change that alters behaviour the incumbent's tests pin fails there, in the fork's own CI. The
  rates are on [Compatibility](/docs/compatibility).

---

# The floor

> The requirements every CLI on burgee meets, and who holds each — runtime, lint, or both. 74 of the floor's 114 are tabled here.

Source: https://burgee.interlace.tools/docs/the-floor

The floor is **114 requirements**: the 109 rows of the requirement tables in
[`.sdlc/intents/burgee/spec.md`](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/intents/burgee/spec.md#requirements--the-cli-floor)
plus the five shape-lock rows Z1–Z5 above them, which is the count that spec states. This
page tables **74** of them — the families below. The spec is the complete list, and what is
built, requirement by requirement, is recorded there too.

Each requirement is held by the **runtime**, by the **lint** plugin
(`eslint-plugin-cli-floor`), or both. A rule with neither is a suggestion, and suggestions are
not a floor. Evidence for every line is an open issue in a leading CLI library — see
[Research](https://github.com/ofri-peretz/burgee/tree/main/.sdlc/research).

## Discoverability

| ID | Requirement | Holds |
| :-- | :-- | :-- |
| F1 | `--schema` prints the full command tree — commands, options, types, defaults, env bindings, examples, deprecations, exit codes — as JSON | runtime |
| F2 | `--help --json` prints help as data; text help is rendered from that data | runtime |
| F3 | Every command declares a description and at least one single-line example | lint |
| F4 | Commands may be grouped and hidden; groups are stable in the schema | runtime |

## Output

| ID | Requirement | Holds |
| :-- | :-- | :-- |
| O1 | `--json` on every command, one envelope `{ ok, data, error?, meta }` | both |
| O2 | No ANSI, spinners, redraws or prompts when stdout is not a TTY or `NO_COLOR` is set; `FORCE_COLOR` overrides | both |
| O3 | Command code writes through the output layer, never `console.*` | lint |
| O4 | Colour via `util.styleText`; no chalk dependency | both |
| O5 | stdout is flushed before every exit path | runtime |

## Errors and lifecycle

| ID | Requirement | Holds |
| :-- | :-- | :-- |
| E1 | Exit codes are a contract: 0 ok, 1 runtime, 2 usage, 3 config, 4 cancelled, 130 SIGINT | both |
| E2 | A runtime failure never prints help; a usage error never prints a stack | both |
| E3 | Every error carries `code`, `message`, `hint` and, where possible, `fix` | runtime |
| E4 | Explicit lifecycle: parse → config → validate → run → render → exit; validation failure stops the handler; async handlers are awaited | runtime |
| E5 | SIGINT restores the terminal and exits 130 | runtime |

## Values and precedence

| ID | Requirement | Holds |
| :-- | :-- | :-- |
| V1 | Flags > env > config file > default, per command, without leaking env into unrelated commands | runtime |
| V2 | Any option may declare an env name; env-bound options appear in help and schema | both |
| V3 | `--explain <option>` reports where each value came from | runtime |
| V4 | `name`, `version`, `description` come from the owning `package.json`, not the monorepo root | runtime |
| V5 | Reserved option names cannot be redefined | lint |

## Validation

| ID | Requirement | Holds |
| :-- | :-- | :-- |
| S1 | Options and positionals are declared once as a schema; types and help are derived | runtime |
| S2 | Relationships are first-class: exactly-one-of, at-least-one-of, implies, conflicts | runtime |
| S3 | Invalid numbers fail validation, never `NaN`; invalid types fail at definition time | runtime |
| S4 | `-` means stdin for file positionals; `--` pass-through reaches child processes intact | runtime |

## Prompts

| ID | Requirement | Holds |
| :-- | :-- | :-- |
| P1 | Every prompt is backed by a flag; a flag value skips the prompt | lint |
| P2 | In a non-TTY the prompt becomes an error naming the flag, exit 2 | runtime |

## Deprecation and testing

| ID | Requirement | Holds |
| :-- | :-- | :-- |
| D1 | Deprecating anything requires a replacement, shown in help, schema and the warning | both |
| D2 | Completions for bash, zsh, fish and PowerShell are generated statically from the schema | runtime |
| T1 | A CLI runs in-process with injected argv, env, stdin, cwd and TTY-ness, returning `{ code, stdout, stderr, json }` | runtime |

## Validation, continued

| ID | Requirement | Holds |
| :-- | :-- | :-- |
| S5 | Every option has one declared type and one canonical camelCase key; kebab-case is derived | runtime |
| S6 | Relations are validated before choices and before the handler | runtime |
| S7 | A `flag` type never consumes a value | runtime |
| S8 | `multiple` options accept repetition and a declared separator | runtime |

## Values, continued

| ID | Requirement | Holds |
| :-- | :-- | :-- |
| V6 | Config discovery order is fixed, documented, and shown by `--explain` | runtime |
| V7 | `extends` merges deeply and resolves from the extending file's `node_modules` | runtime |

## Help

| ID | Requirement | Holds |
| :-- | :-- | :-- |
| H1 | Help is rendered from the manifest only | runtime |
| H2 | Examples are single-line and copy-pasteable | both |
| H3 | Width comes from the runtime, default 100 in non-TTY | runtime |
| H4 | Command options render before global options | runtime |
| H5 | Deprecations and env names render inline | runtime |
| H6 | Type hints are off by default | runtime |

## Completions, continued

| ID | Requirement | Holds |
| :-- | :-- | :-- |
| D3 | Completions never execute the CLI unless an option is marked dynamic | runtime |
| D4 | Every shell script is snapshot-pinned and exercised by that shell in CI | runtime |
| D5 | A Fig spec is exported from the same node | runtime |

## Prompts, continued

| ID | Requirement | Holds |
| :-- | :-- | :-- |
| P3 | Cancellation exits `CANCELLED` (4), never `RUNTIME` | runtime |

## Modularity

| ID | Requirement | Holds |
| :-- | :-- | :-- |
| M1 | Every command carries a group | runtime |
| M2 | The manifest is complete before any handler module loads | runtime |
| M3 | Every plugin's contributions are attributed in the manifest | runtime |
| M4 | Shared options are declared once and copied per command | runtime |
| M5 | A deprecated command names its replacement in help, schema and warning | both |
| M6 | `resolveCommand` and `runCommand` are public | runtime |

## Packaging

| ID | Requirement | Holds |
| :-- | :-- | :-- |
| K1 | No dependency outside the burgee family in any published package; hosts and UI libraries are peers | lock |
| K2 | ESM only, Node 20.19+ or 22.13+ (restated 2026-09-23, D-132; was Node 24 or newer) | lock |
| K3 | Node natives over packages | both |
| K4 | An artifact gate runs on the built output before publish | release |
| K5 | Per-package size budget, ratcheted | lock |
| K6 | Weight is paid per import: compatibility and host quirks live behind their own specifiers, never behind a runtime flag | lock |

## Compatibility

Every claim about a host is graded by that host's own test suite, so "compatible" is a
number rather than an adjective. The rate is published on every release.

| ID | Requirement | Holds |
| :-- | :-- | :-- |
| C1 | Every package declares a supported host range; the host's own suite runs against it at every supported major | CI |
| C2 | A compatibility front-end is graded by the host's own suite through a one-line shim; the rate is published per release | CI |
| C3 | Every package is tested on every Node LTS in its `engines` range, across Linux, macOS and Windows | CI |
| C4 | Every intentional divergence has an id, a written reason, and a test asserting it — an unlisted failure is a bug | lock |
| C5 | Pass rates ratchet; lowering one requires editing the baseline with a reason | CI |
| C6 | Vendored suites record their upstream commit; a scheduled job opens a pull request when the count changes | workflow |

## Benchmarks

Four axes, because there are four kinds of public claim. Every number the project cites
anywhere links back to the generated benchmarks page.

| ID | Requirement | Holds |
| :-- | :-- | :-- |
| B1 | Agent cost: tokens, turns and success per task, layer on versus off | band |
| B2 | Performance: cold start p50/p95 over 30 or more spawns, always including a bare-node floor row | band |
| B3 | Compatibility: per-host pass rate, read from the oracle, never recomputed | band |
| B4 | Weight: bundled size per entry point against a published target; a core-only import pulls zero front-end bytes | band |
| B5 | Every axis emits one JSON shape, so one collector reads all of them | lock |
| B6 | Performance, compatibility and weight gate every pull request; agent cost runs weekly | CI |
| B7 | Every public number links to the generated benchmarks page | lock |

## Agent interface

The manifest already carries everything an MCP tool definition needs. These requirements
turn it into a served interface rather than a document.

| ID | Requirement | Holds |
| :-- | :-- | :-- |
| N1 | `--mcp` serves the CLI over MCP stdio; tool definitions are generated from the manifest, never hand-written | runtime |
| N2 | A command is kept from agents only by a declaration: `effects: 'withheld'`. Every runnable command on burgee's own API declares its effects; a façade command that declared nothing is listed as `effects: 'undeclared'`, with no hints | both |
| N3 | No dependency outside the burgee family: JSON-RPC over stdio against `node:readline` | lock |
| N4 | Tool results are the standard envelope, so MCP and `--json` callers see identical payloads | runtime |
| N5 | `--mcp` implies non-TTY: no prompts, no colour, structured errors | runtime |

---

# Switching from cac

> A cac alternative, measured against it rather than dropped in: there is no burgee/cac, so moving means rewriting each command. cac is far smaller and starts faster; this is when that matters and when --json, --schema and --mcp matter more.

Source: https://burgee.interlace.tools/docs/vs/cac

burgee is **not** a drop-in for cac. There is no `burgee/cac` and `burgee migrate` does not
rewrite a cac import. [Compatibility](/docs/compatibility) lists a cac front end as
**planned** and deferred: cac's downloads are almost entirely vite and vitest bundling it,
not developers choosing it, so a façade would convert few people. Until one exists and is
graded by cac's own tests, moving a cac CLI to burgee is a rewrite, and this page is here to
help you decide whether it is worth one.

## Is there a drop-in?

No. burgee's `package.json` exports front ends for commander (`burgee/commander`), yargs
(`burgee/yargs`) and meow (`burgee/meow`), each graded by that host's own test suite.
Nothing is exported for cac, so no cac program runs on burgee unchanged, and this page never
calls burgee cac-compatible.

## When cac is the better choice

cac is the lightest framework in the landscape, and burgee's own gates say it is lighter
than burgee. Measured against `cac@7.0.0`, the version the benchmark suite resolves, with
each ratio taken between the two in the same run:

- **Bundle size.** cac alone is the lighter bundle, and burgee is 2.343× it: burgee's
  core bundles to 24,484 bytes and cac to 10,452. The `lighter-than-cac` gate is a
  downward-only ratchet that holds the ratio within 2.35× and may only be lowered (D-157).
- **Cold start.** cac starts faster in every run on record. Across the 178 runs committed
  under `benchmarks/results/cli-benchmarks/`, burgee's full-run cold start is 1.29×–2.13×
  cac's and never at or below 1. The 174 CI runs fall between 1.29× and 1.55×; the four
  higher figures are from a developer laptop. The latest CI run,
  `2026-09-28-d5bd4e6-ci.json` (2026-09-28), measured **1.481×**. At or below cac is not
  reachable, so the gate is a downward-only ratchet at 1.55×, set from CI's own spread
  (D-157).
- **Installed size.** 1690 KB for burgee against 40 KB for cac.

Those gaps are not scheduled to close. The README says why: cac's bytes are a parser and a
help renderer, and burgee's are that plus coercion, choices, option relations, Standard
Schema, config precedence, bounded shutdown, terminal restore and agent detection, so
closing them would mean deleting the product. If your CLI needs none of that and every
byte counts, choose cac.

## When burgee is the better choice

- **You would otherwise add the rest yourself.** A cac program that wants its config file
  read, its shutdown bounded on every path out and its cursor handed back on Ctrl-C
  installs `cosmiconfig`, `exit-hook` and `restore-cursor`. Against that stack burgee's
  `lighter-than-cac-at-parity` gate is met (0.251×): 24,484 bytes against 97,692. Both
  gates are the README's, and every bundle figure on this page is rewritten from a fresh
  build by `npm run readme:gates`, so it cannot drift from what the build measures.
- **You want an agent to drive it.** The comparison marks cac without a `--json` envelope,
  an exit-code contract, `--schema`, `--mcp` or shell completions. burgee projects all five
  from one declaration; see [Your CLI is an agent tool](/docs/agent-surfaces).
- **You want plugins.** The comparison marks cac without them; burgee's
  [plugins](/docs/plugins) are shared across programs.

## Weight against cac

From [burgee vs the alternatives](/docs/comparison), where both sides are measured by
`npm run bench` in one run on one machine (2026-10-08, CI), with downloads from the research
snapshot of 2026-09-06. Milliseconds are a property of the machine that measured them; the
ratios above are the figures that cancel it out:

| | burgee | cac |
| :-- | --: | --: |
| Downloads / week | new | 49.4M |
| Runtime dependencies | 5, none outside the burgee family | 0 |
| Full CLI run over bare node | +20.3 ms | +3.8 ms |
| Installed size | 1690 KB | 40 KB |

cac wins every row, and every row stays on the page. The case for burgee is the capability
list above, not weight.

## Moving a command across

There is no import to swap, so each `cli.command()` chain becomes a `defineCommand`. The
shapes are close: cac's `<name>` in the command string becomes an entry in `arguments`,
each `.option()` becomes a key in `options`, and `.action()` becomes `run`. What is new is
`effects`, which says what running the command does to the world, and which `--mcp` reads.

Before, with `cac` 7.0.0:

```js
import cac from 'cac';

const cli = cac('hello');
cli
  .command('greet <name>', 'Greet someone')
  .option('--shout', 'uppercase it')
  .action((name, options) => {
    const line = `Hello, ${name}`;
    console.log(options.shout ? line.toUpperCase() : line);
  });
cli.help();
cli.parse();
```

After, with burgee:

```js
import { defineCommand, defineProgram, run } from 'burgee';

const program = defineProgram({
  name: 'hello',
  commands: [
    defineCommand({
      name: 'greet',
      description: 'Greet someone',
      effects: 'read_only',
      arguments: [{ name: 'name', required: true }],
      options: { shout: { type: 'boolean', description: 'uppercase it' } },
      run: ({ positionals, options }) => {
        const line = `Hello, ${positionals[0]}`;
        return options.shout ? line.toUpperCase() : line;
      },
    }),
  ],
});

await run(program);
```

The handler returns its result instead of printing it, so `greet ada --json` answers
`{"ok":true,"data":"Hello, ada",…}` and a missing name exits `2`. Help needs no
`cli.help()`: every burgee program has it.

---

# Switching from citty

> A citty alternative, measured against it rather than dropped in: there is no burgee/citty, but both declare a command as one object, so the rewrite is short. When citty is the better choice, when burgee is, and what moving looks like.

Source: https://burgee.interlace.tools/docs/vs/citty

burgee is **not** a drop-in for citty. There is no `burgee/citty` and `burgee migrate` does
not rewrite a citty import. [Compatibility](/docs/compatibility) lists a citty front end as
**planned** and deferred, for the same reason as cac: nitro and unjs bundle citty, so most of
its downloads are not developers choosing it. Until a front end exists and is graded by
citty's own tests, moving a citty CLI to burgee is a rewrite. It is a short one: both declare
a command as a single object with a `run` function.

## Is there a drop-in?

No. burgee's `package.json` exports front ends for commander (`burgee/commander`), yargs
(`burgee/yargs`) and meow (`burgee/meow`), each graded by that host's own test suite.
Nothing is exported for citty, so no citty program runs on burgee unchanged, and this page
never calls burgee citty-compatible.

## When citty is the better choice

- **You want it tiny.** The comparison records citty's manifest as declaring none, against
  burgee's five, and the research survey timed its startup at +6 ms over bare node, on
  its own machine (the figures are below).
- **You are building inside unjs.** The research snapshot records citty as bundled in nitro
  and the unjs tools. If your CLI lives next to them, matching their conventions is worth
  more than anything on this page.
- **You want lifecycle hooks on the command itself.** citty 0.2.2, the version read for this
  page, declares `setup` and `cleanup` on a command and a `plugins` list of the same two
  hooks. Those plugins run around a command and add none, which is why the comparison's
  *Plugins that add commands* row still marks citty ❌.

## When burgee is the better choice

- **You want an agent to drive it.** citty's own tracker asks for this: citty
  [#187](https://github.com/unjs/citty/issues/187) wants a command's output returned so it
  can be fed back to an LLM, and [#117](https://github.com/unjs/citty/issues/117) wants usage
  returned as data rather than a string (both open at the research snapshot). The comparison
  marks citty without a `--json` envelope, an exit-code contract, `--schema` or `--mcp`;
  burgee projects all four from one declaration. See
  [Your CLI is an agent tool](/docs/agent-surfaces).
- **You want completions for four shells.** The comparison marks citty's completions as
  *partial*, and the research lists citty [#217](https://github.com/unjs/citty/issues/217),
  [#168](https://github.com/unjs/citty/issues/168) and
  [#59](https://github.com/unjs/citty/issues/59) among the completion requests. burgee
  generates static scripts for bash, zsh, fish and PowerShell.
- **You want validation beyond the parser.** citty [#84](https://github.com/unjs/citty/issues/84),
  [#103](https://github.com/unjs/citty/issues/103) and
  [#138](https://github.com/unjs/citty/issues/138) asked for a validator, a normaliser and a
  `number` type (0.2.2's argument types are still `boolean`, `string`, `enum` and
  `positional`); burgee has `number`, `choices`, option relations and Standard Schema.

Both derive the handler's types from the declaration; the comparison marks it ✅ for each.
The full reading of citty's tracker is on [Research](/docs/research).

## Weight against citty

burgee's cells are from [burgee vs the alternatives](/docs/comparison), measured by
`npm run bench` (2026-10-08, one CI runner). citty's download count and startup are from the
research snapshot of 2026-09-06 (`competitor-landscape.md` §1 and §2), timed on a different
machine at a different time and not reproduced by the suite, so the two startup cells are
not a like-for-like measurement. The suite does not install citty, so its installed size is
**not measured here**:

| | burgee | citty |
| :-- | --: | --: |
| Downloads / week | new | 30.5M |
| Runtime dependencies | 5, none outside the burgee family | 0 |
| Full CLI run over bare node | +20.3 ms | +6 ms (surveyed, another machine) |
| Installed size | 1690 KB | not measured here |

citty wins on dependencies and downloads, and its surveyed startup is lower too. The case
for burgee is the capability list above, not weight.

## Moving a command across

There is no import to swap, but the shapes line up: `meta.name` and `meta.description`
move to the top level, a `positional` arg becomes an entry in `arguments`, every other arg
becomes a key in `options`, and `run` stays `run`. What is new is `effects`, which says what
running the command does to the world, and which `--mcp` reads.

Before, with `citty` 0.2.2:

```js
import { defineCommand, runMain } from 'citty';

const greet = defineCommand({
  meta: { name: 'greet', description: 'Greet someone' },
  args: {
    name: { type: 'positional', required: true },
    shout: { type: 'boolean', description: 'uppercase it' },
  },
  run({ args }) {
    const line = `Hello, ${args.name}`;
    console.log(args.shout ? line.toUpperCase() : line);
  },
});

runMain(defineCommand({ meta: { name: 'hello' }, subCommands: { greet } }));
```

After, with burgee:

```js
import { defineCommand, defineProgram, run } from 'burgee';

const program = defineProgram({
  name: 'hello',
  commands: [
    defineCommand({
      name: 'greet',
      description: 'Greet someone',
      effects: 'read_only',
      arguments: [{ name: 'name', required: true }],
      options: { shout: { type: 'boolean', description: 'uppercase it' } },
      run: ({ positionals, options }) => {
        const line = `Hello, ${positionals[0]}`;
        return options.shout ? line.toUpperCase() : line;
      },
    }),
  ],
});

await run(program);
```

The handler returns its result instead of printing it, so `greet ada --json` answers
`{"ok":true,"data":"Hello, ada",…}` and a missing name exits `2`. citty's `setup`, `cleanup`
and plugins have no one-for-one equivalent. The nearest for `cleanup` is `ctx.onExit()`,
called inside `run`, which runs on every path out, Ctrl-C and an uncaught throw included;
the rest is a design decision per command, not a rewrite of syntax.

---

# Switching from commander

> A commander alternative that is drop-in compatible: change one import, keep your code and tests, and gain --json, --schema, --mcp and shell completions. Graded by commander's own test suite.

Source: https://burgee.interlace.tools/docs/vs/commander

burgee is a **commander alternative** you adopt by changing one import. It is not a new
API to learn and not a wrapper around commander: `burgee/commander` implements commander's
API itself, and commander's own test suite is the grade.

## Migrate from commander in one import

```diff
- import { Command } from 'commander';
+ import { Command } from 'burgee/commander';
```

Your program and your tests stay as they are. On a larger codebase, `npx burgee migrate
--dry-run` finds every `commander` import and prints the rewrite before it makes one; it
refuses, by file and line, anything it cannot rewrite mechanically, and leaves that file
untouched.

## Is it really compatible with commander?

Compatibility is graded, not claimed. commander's own test suite — vendored, unmodified
apart from the import specifier — runs against `burgee/commander` in CI, beside a control
that runs the same suite against real commander:

| | passing | rate |
| :-- | --: | --: |
| `burgee/commander` | 1360 / 1360 | 100.0% |
| commander itself (control) | 1360 / 1360 | 100.0% |

From [Compatibility](/docs/compatibility), which `npm run compat:page` generates from the
oracle's last run; this table is copied from it and that page is the authority. A façade
is never called "compatible" until its host's own suite passes 100%.

## What you gain over commander

The same program, after the import swap, answers four things commander cannot:

- **`--json`** — every command's result in one stable envelope, `{ "ok": true, "data": … }`,
  and every failure in the same place: `{ "ok": false, "error": { "code", "message" } }` on
  stdout, alone, whether commander refused the command line or the action threw — with the
  exit code the error names (`AuthError` exits 5). Through 0.11.1 an action that threw under a
  plain `parseAsync(process.argv)` escaped as a stack trace instead. No stdout scraping. `data` is what the action returns, so
  an action that only prints gives `data: null` — commander actions return nothing; return
  the value (`.action(() => ({ lines }))`) and it is `data`.
- **`--schema`** — the whole command tree as data: commands, arguments, options, choices,
  defaults and a JSON Schema per command. It runs no handler and reads no config, so it is
  safe for an agent to call first.
- **`--mcp`** — the same commands served as MCP tools over stdio. Every command with an
  action is a tool; one that declared nothing is annotated `effects: 'undeclared'` with no
  hints, `.effects('read_only')` (or `idempotent`, `non_idempotent`) adds them, and
  `.effects('withheld')` keeps a command out. An action that prints is still a useful
  tool: its printed output becomes the tool result instead of corrupting the stream.
- **Completions** — `completion bash | zsh | fish | pwsh`, generated from the same
  declaration; pressing TAB never runs your program.

And an exit-code contract an agent can act on: `2` means *rewrite the command*, any other
non-zero means *the command was fine and the world was not*. Details on
[Your CLI is an agent tool](/docs/agent-surfaces).

Plugins, too: commander's plugin RFC
([#2505](https://github.com/tj/commander.js/issues/2505)) was closed for inactivity on
2026-10-09 without one, while a burgee
plugin works on commander syntax, yargs syntax and native alike — see
[Plugins](/docs/plugins).

## What commander still does better

Weight. From the root README's *Measured* table (2026-10-08, one CI runner, generated by
`npm run bench` — see [Benchmarks](/docs/benchmarks) and
[burgee vs the alternatives](/docs/comparison)):

| | burgee | commander |
| :-- | --: | --: |
| Runtime dependencies | 5, none outside the burgee family | 0 |
| Full CLI run over bare node | +20.3 ms | +14.8 ms |
| Installed size | 1690 KB | 203 KB |

Against commander alone, `burgee/commander` is the heavier bundle (1.415×). Lighter than
commander alone is not reachable while the front end also carries a manifest, a schema and an
MCP server, so the `lighter-than-commander` gate is a downward-only ratchet instead: it holds
the ratio within 1.42× and may only be lowered (D-157). Against commander *plus* what a
commander user installs to match burgee's config, shutdown and
cursor handling, it is met (0.438×). Both rows are on the README and neither is hidden. And
commander has users; burgee is new.

## When to switch

- You want your CLI usable by an AI agent without writing tool definitions by hand.
- You want `--json` output and exit codes that mean something, on every command.
- You want plugins shared across programs.

If none of that matters and bundle bytes do, commander is the lighter choice today.

---

# Switching from oclif

> An oclif alternative, measured against it rather than dropped in: there is no burgee/oclif, so moving means rewriting each command class. When oclif is the better choice, when burgee is, and what the rewrite looks like.

Source: https://burgee.interlace.tools/docs/vs/oclif

burgee is **not** a drop-in for oclif. There is no `burgee/oclif`, `burgee migrate` does not
rewrite an oclif import, and none is planned: [Compatibility](/docs/compatibility) lists oclif
as **rejected**, because its API is inseparable from its shape — a project layout, a build
step and a generator — and a façade could not be adopted without adopting that shape. Moving
an oclif CLI to burgee is a rewrite, one command at a time. This page is here to help you
decide whether that rewrite is worth it, and it says so where it is not.

## Is there a drop-in?

No. burgee's `package.json` exports front ends for commander (`burgee/commander`), yargs
(`burgee/yargs`) and meow (`burgee/meow`), each graded by that host's own test suite.
Nothing is exported for oclif and nothing is graded against it, so no oclif program runs on
burgee unchanged, and this page never calls burgee oclif-compatible.

## When oclif is the better choice

- **You want its ecosystem.** oclif has plugins — the comparison marks them ✅ — and a set of
  published ones around them. The `@oclif/core` 4.8.0 read for this page configures
  `jitPlugins` (installed on first use), an `update` block with `autoupdate` and S3 hosting,
  and `macos` signing settings; the Salesforce CLI it was read from installs
  `@oclif/plugin-plugins`, `@oclif/plugin-update` and `@oclif/plugin-autocomplete` beside it.
  burgee has [plugins](/docs/plugins), but no installer or self-update configuration, and no
  published plugins with oclif's years of use behind them.
- **You are already at scale on it.** The research snapshot records `@oclif/core` as what the
  Salesforce and Heroku CLIs are built on. A large CLI that already works, with a team that
  knows oclif, gains less from a rewrite than a new one does.
- **You want completions and derived types today, from a mature project.** The comparison
  marks both ✅ for oclif, as it does for burgee; oclif has had them far longer.

## When burgee is the better choice

- **You want one file and no build step.** burgee's is enforced by a test that installs the
  tarball, writes one file and runs it. The comparison marks oclif's as *scaffold*. That is
  not a hard wall: `@oclif/core` 4.8.0 can also load commands from an explicit export or a
  single class, rather than a directory it globs.
- **You want an agent to drive it.** burgee projects `--json`, `--schema` and `--mcp` from the
  same declaration as help. The comparison marks oclif's JSON envelope and exit-code
  contract as *partial* — `static enableJsonFlag` is opt-in per command — its `--schema`
  equivalent as a *manifest*, and `--mcp` as not there. See
  [Your CLI is an agent tool](/docs/agent-surfaces).
- **You want fewer dependencies.** `@oclif/core` brings eighteen runtime dependencies (the
  comparison's figure, and the count in the 4.8.0 manifest read for this page); burgee brings
  five, none outside the burgee family. oclif's own tracker raises it: oclif/core
  [#1627](https://github.com/oclif/core/issues/1627) (2026-07) notes that several of them now
  have native Node equivalents.

The same research read every open issue on oclif/core and oclif/oclif. Two of them are the
layer burgee is built around: oclif/core [#854](https://github.com/oclif/core/issues/854)
finds it "hard to tell whether a user really typed that flag or is just a default", which
burgee's `--json` answers in `meta.provenance` — each option with a value says whether it
came from a flag or its default — and oclif/oclif
[#958](https://github.com/oclif/oclif/issues/958) is Ctrl+C and raw-mode handling. The full
reading is on [Research](/docs/research).

## Weight against oclif

burgee's cells are from [burgee vs the alternatives](/docs/comparison), measured by
`npm run bench` (2026-10-08, one CI runner). oclif's download count is from the research
snapshot of 2026-09-06, and its dependency count is the one in the 4.8.0 manifest. The
benchmark suite does not run oclif, so its startup and installed size are **not measured
here**, and this page states no figure for them:

| | burgee | @oclif/core |
| :-- | --: | --: |
| Downloads / week | new | 10.9M |
| Runtime dependencies | 5, none outside the burgee family | 18 |
| Full CLI run over bare node | +20.3 ms | not measured here |
| Installed size | 1690 KB | not measured here |

With no measured oclif figure, this page claims no speed or size result either way. And
oclif has users; burgee is new.

## Moving a command across

There is no import to swap, so each command class becomes a `defineCommand`. The flags and
arguments move nearly one for one; what is new is `effects`, which says what running the
command does to the world, and which `--mcp` reads.

Before, with `@oclif/core` 4.8.0:

```ts
// src/commands/greet.ts, found through the oclif.commands setting in package.json
import { Args, Command, Flags } from '@oclif/core';

export default class Greet extends Command {
  static description = 'Greet someone';
  static args = { name: Args.string({ required: true }) };
  static flags = { shout: Flags.boolean({ description: 'uppercase it' }) };

  async run() {
    const { args, flags } = await this.parse(Greet);
    const line = `Hello, ${args.name}`;
    this.log(flags.shout ? line.toUpperCase() : line);
  }
}
```

After, with burgee:

```ts
// cli.ts, the whole CLI
import { defineCommand, defineProgram, run } from 'burgee';

const program = defineProgram({
  name: 'hello',
  commands: [
    defineCommand({
      name: 'greet',
      description: 'Greet someone',
      effects: 'read_only',
      arguments: [{ name: 'name', required: true }],
      options: { shout: { type: 'boolean', description: 'uppercase it' } },
      run: ({ positionals, options }) => {
        const line = `Hello, ${positionals[0]}`;
        return options.shout ? line.toUpperCase() : line;
      },
    }),
  ],
});

await run(program);
```

The handler returns its result instead of logging it, so `greet ada --json` answers
`{"ok":true,"data":"Hello, ada",…}` and a missing name exits `2`. oclif's plugins, hooks and
installer configuration have no one-for-one equivalent, and moving them is design work,
not a rewrite of syntax.

---

# Switching from yargs

> A yargs alternative that is drop-in compatible: change one import, keep your code and tests, and gain --json, --schema, --mcp and shell completions — with no dependency outside the burgee family where yargs has six.

Source: https://burgee.interlace.tools/docs/vs/yargs

burgee is a **yargs alternative** you adopt by changing one import. `burgee/yargs`
implements yargs' API itself — the factory, the instance, the helpers — and yargs' own test
suite is the grade.

## Migrate from yargs in one import

```diff
- import yargs from 'yargs';
- import { hideBin } from 'yargs/helpers';
+ import yargs from 'burgee/yargs';
+ import { hideBin } from 'burgee/yargs/helpers';
```

Your program and your tests stay as they are. `npx burgee migrate --dry-run` rewrites
`yargs`, `yargs/yargs` and `yargs/helpers` across a codebase, prints the plan first, and
refuses — by file and line — anything it cannot rewrite mechanically.

Your types move with the import. `burgee/yargs` exports what a typed program reads from
`@types/yargs` — `Argv`, `Arguments`, `CommandModule`, `Options`, `InferredOptionTypes` and
the rest — so `import yargs, { type Argv } from 'burgee/yargs'` compiles, and a typed chain
infers `argv` exactly as it did.

## Is it really compatible with yargs?

Compatibility is graded, not claimed. yargs' own test suite — vendored, unmodified apart
from the import specifier — runs against `burgee/yargs` in CI, beside a control that runs
the same suite against real yargs:

| | passing | rate |
| :-- | --: | --: |
| `burgee/yargs` | 816 / 816 | 100.0% |
| yargs itself (control) | 814 / 816 | 99.8% |

From [Compatibility](/docs/compatibility), which `npm run compat:page` generates from the
oracle's last run; this table is copied from it and that page is the authority. Rates are
measured against the control's total, so a file that fails to import cannot flatter the
number.

## What you gain over yargs

- **`--json`** — every command's result in one stable envelope, `{ "ok": true, "data": … }`,
  and every failure as one `{ "ok": false, "error": { "code", "message" } }` on stdout, with
  the exit code the error names — a handler that throws included, which through 0.11.1 could
  escape `parseAsync()` as a stack trace.
- **`--schema`** — the command tree as data, with a JSON Schema per command; no handler
  runs, so an agent can call it first.
- **`--mcp`** — the same commands as MCP tools over stdio. A command that declared nothing
  is listed as `effects: 'undeclared'` with no hints; `.effects('read_only')` adds them and
  `.effects('withheld')` keeps a command out.
- **Completions** — `completion bash | zsh | fish | pwsh`, static scripts generated from the
  declaration.
- **An exit-code contract** — `2` means *rewrite the command*; any other non-zero means the
  command was fine and the world was not.

yargs offers middleware on one program; a burgee [plugin](/docs/plugins) is written once and
shared across programs, and works on yargs syntax, commander syntax and native alike.

## Weight against yargs

From the root README's *Measured* table (2026-10-08, one CI runner, generated by
`npm run bench` — see [Benchmarks](/docs/benchmarks)):

| | burgee | yargs |
| :-- | --: | --: |
| Runtime dependencies | 5, none outside the burgee family | 6 |
| Full CLI run over bare node | +20.3 ms | +75.0 ms |
| Installed size | 1690 KB | 515 KB |

The `lighter-than-yargs` gate — `burgee/yargs` lighter in a bundle than yargs — is met
(0.974×). Installed size is larger, and stays on the page.

## When to switch

- You want your CLI usable by an AI agent without writing tool definitions by hand.
- You want fewer packages in your install tree: yargs brings six runtime dependencies,
  burgee none outside the burgee family.
- You want `--json`, `--schema` and completions from the definition you already wrote.

---

# Weight, per subpath

> What every published entry point costs a consumer's bundle, at both ends of the tree-shaking range.

Source: https://burgee.interlace.tools/docs/weight

{/* Generated by `npm run weight:page`. Do not edit by hand. */}

Generated 2026-10-20 at commit `de84afa45b`.

Every entry point this repository publishes, and what it costs a consumer's bundle. **109 subpaths across 10 packages**, every export of every one of them bundled on its own.

Three numbers, because tree shaking makes this a range rather than a figure:

- **Cheapest** — the export that costs least to import, and its name.
- **Dearest** — the export that costs most. The one worth knowing about before you reach for it.
- **Everything** — the whole namespace re-exported, so nothing can be shaken away.

A wide spread means the subpath shakes well and most consumers pay near the left-hand number.
A narrow one means it arrives as a unit, which is worth knowing before importing it rather than
after.

All three are the **initial load**: the entry chunk plus the transitive closure of its `import`
statements, bundled with `esbuild --bundle --minify --format=esm --platform=node --splitting`.
A chunk reached only through `await import()` costs nothing until that branch runs, which is
what a real bundler does and what the figures on [/docs/benchmarks](/docs/benchmarks) mean too — the
same function produces both.

### `bellpull`

| Subpath | Exports | Cheapest | Dearest | Everything |
| :--- | ---: | ---: | ---: | ---: |
| `bellpull/node-which` | 1 | `default` 1,977 | `default` 1,977 | 1,990 |
| `bellpull/which` | 11 | `sep` 87 | `whichOrThrowSync` 2,043 | 2,534 |
| `bellpull/plugin` | 9 | `CONTRACT` 31 | `register` 3,087 | 4,253 |
| `bellpull/cross-spawn` | 6 | `sync` 4,948 | `default` 4,972 | 5,048 |
| `bellpull` | 26 | `name` 36 | `run` 5,883 | 8,251 |

### `burgee`

| Subpath | Exports | Cheapest | Dearest | Everything |
| :--- | ---: | ---: | ---: | ---: |
| `burgee/contrast` | 9 | `AA` 44 | `auditBurgee` 1,478 | 1,776 |
| `burgee/config` | 5 | `ConfigError` 207 | `resolve` 2,149 | 3,258 |
| `burgee/plugin` | 4 | `CONTRACT` 31 | `definePlugin` 4,464 | 4,509 |
| `burgee/brand` | 14 | `BURGEE_FLAG` 314 | `defineBurgee` 6,183 | 6,532 |
| `burgee/mcp` | 4 | `MCP_PROTOCOL_VERSION` 185 | `serveMcp` 7,628 | 7,686 |
| `burgee/schema` | 5 | `summaryOf` 747 | `Manifest` 5,746 | 8,613 |
| `burgee/completions` | 4 | `SHELLS` 56 | `renderCompletion` 9,306 | 10,179 |
| `burgee/yargs/parser` | 7 | `Parser` 15,812 | `default` 15,833 | 15,951 |
| `burgee/yargs/helpers` | 3 | `hideBin` 982 | `Parser` 15,812 | 17,127 |
| `burgee/help` | 1 | `renderHelp` 17,142 | `renderHelp` 17,142 | 17,142 |
| `burgee/testing` | 12 | `ExitCode` 1,057 | `runBurgee` 20,008 | 21,174 |
| `burgee/meow` | 1 | `default` 26,772 | `default` 26,772 | 26,762 |
| `burgee` | 18 | `camel` 3,098 | `run` 24,484 | 26,934 |
| `burgee/cli` | 7 | `program` 40,470 | `pluginCheckCommand` 40,481 | 40,589 |
| `burgee/commander` | 14 | `Help` 55,290 | `createArgument` 55,326 | 55,595 |
| `burgee/commander/extra-typings` | 14 | `Help` 55,290 | `createArgument` 55,326 | 55,595 |
| `burgee/commander/v14` | 14 | `Help` 55,290 | `createCommand` 55,647 | 55,944 |
| `burgee/yargs` | 15 | `YError` 108,714 | `isYargsInstance` 108,790 | 109,089 |
| `burgee/yargs/v17/yargs` | 1 | `default` 110,049 | `default` 110,049 | 110,061 |
| `burgee/yargs/v17` | 15 | `YError` 109,905 | `isYargsInstance` 109,981 | 110,254 |

### `caique`

| Subpath | Exports | Cheapest | Dearest | Everything |
| :--- | ---: | ---: | ---: | ---: |
| `caique/spec` | 3 | `flagOf` 50 | `problemWith` 413 | 549 |
| `caique/terminal` | 2 | `streamsOf` 67 | `createIo` 886 | 901 |
| `caique/decide` | 1 | `decide` 1,011 | `decide` 1,011 | 1,011 |
| `caique/ask` | 2 | `projection` 1,772 | `ask` 2,092 | 2,172 |
| `caique/locale` | 3 | `render` 1,625 | `sayFor` 3,924 | 3,954 |
| `caique/keys` | 8 | `canReadKeys` 283 | `readKeys` 3,108 | 4,678 |
| `caique/binding` | 2 | `localise` 125 | `resolvePrompts` 4,693 | 4,707 |
| `caique/plugin` | 10 | `CONTRACT` 31 | `projectionOf` 2,705 | 4,949 |
| `caique/editor` | 3 | `submissions` 148 | `editor` 10,834 | 10,995 |
| `caique/raw` | 4 | `canRender` 307 | `askList` 12,761 | 12,902 |
| `caique` | 23 | `flagOf` 50 | `askList` 12,760 | 19,310 |
| `caique/inquirer` | 25 | `isShiftKey` 77 | `createPrompt` 18,995 | 22,923 |
| `caique/clack` | 60 | `S_BAR` 1,188 | `path` 28,040 | 44,498 |
| `caique/inquirer/prompts` | 11 | `Separator` 1,323 | `editor` 28,469 | 44,683 |

### `closeout`

| Subpath | Exports | Cheapest | Dearest | Everything |
| :--- | ---: | ---: | ---: | ---: |
| `closeout/once` | 1 | `once` 238 | `once` 238 | 238 |
| `closeout/onetime` | 1 | `default` 724 | `default` 724 | 716 |
| `closeout/cursor` | 11 | `HIDE_CURSOR` 44 | `rawMode` 329 | 943 |
| `closeout/signal-exit/signals` | 2 | `default` 1,199 | `signals` 1,229 | 1,327 |
| `closeout/exit-hook` | 3 | `gracefulExit` 1,260 | `asyncExitHook` 1,688 | 1,848 |
| `closeout/plugin` | 9 | `CONTRACT` 31 | `register` 1,818 | 2,340 |
| `closeout/signal-exit` | 4 | `load` 2,655 | `signals` 2,658 | 2,692 |
| `closeout/restore-cursor` | 1 | `default` 4,340 | `default` 4,340 | 4,330 |
| `closeout/cli-cursor` | 1 | `default` 4,578 | `default` 4,578 | 4,568 |
| `closeout` | 23 | `DEFAULT_DEADLINE` 41 | `rawMode` 4,866 | 6,283 |

### `controlroom`

| Subpath | Exports | Cheapest | Dearest | Everything |
| :--- | ---: | ---: | ---: | ---: |
| `controlroom/plugin` | 6 | `CONTRACT` 31 | `registered` 3,720 | 3,828 |
| `controlroom` | 14 | `status` 38 | `open` 41,982 | 42,902 |
| `controlroom/ink` | 24 | `measureElement` 568 | `render` 114,667 | 121,091 |

### `flagstaff`

| Subpath | Exports | Cheapest | Dearest | Everything |
| :--- | ---: | ---: | ---: | ---: |
| `flagstaff/import` | 2 | `fromCliBoxes` 189 | `fromCliSpinners` 319 | 499 |
| `flagstaff/diff` | 1 | `diff` 1,127 | `diff` 1,127 | 1,127 |
| `flagstaff/progress` | 1 | `progress` 1,179 | `progress` 1,179 | 1,179 |
| `flagstaff/markdown` | 2 | `markdownBlocks` 1,032 | `markdown` 2,317 | 2,337 |
| `flagstaff/plugin` | 8 | `CONTRACT` 6,141 | `lookupSpinner` 6,402 | 6,794 |
| `flagstaff/tab-bar` | 1 | `tabBar` 6,940 | `tabBar` 6,940 | 6,940 |
| `flagstaff/spinner` | 1 | `spinner` 7,207 | `spinner` 7,207 | 7,209 |
| `flagstaff/tasks` | 1 | `tasks` 7,398 | `tasks` 7,398 | 7,400 |
| `flagstaff/log-tail` | 1 | `logTail` 7,475 | `logTail` 7,475 | 7,475 |
| `flagstaff/loop` | 3 | `manualClock` 519 | `hoist` 12,871 | 13,407 |
| `flagstaff/log-update` | 3 | `createLogUpdate` 18,741 | `default` 18,751 | 18,785 |
| `flagstaff/table` | 2 | `table` 19,184 | `tableComponent` 19,483 | 19,495 |
| `flagstaff/box` | 2 | `box` 20,696 | `boxComponent` 21,381 | 21,391 |
| `flagstaff/cli-table3` | 14 | `Cell` 24,380 | `default` 24,403 | 24,618 |
| `flagstaff/boxen` | 2 | `_borderStyles` 1,199 | `default` 28,671 | 28,681 |
| `flagstaff` | 20 | `fromCliBoxes` 189 | `boxComponent` 21,381 | 37,106 |
| `flagstaff/ora` | 4 | `spinners` 37,473 | `oraPromise` 56,334 | 56,373 |

### `linegauge`

| Subpath | Exports | Cheapest | Dearest | Everything |
| :--- | ---: | ---: | ---: | ---: |
| `linegauge/strip` | 2 | `strip` 262 | `default` 272 | 275 |
| `linegauge/plugin` | 7 | `CONTRACT` 31 | `register` 2,998 | 3,112 |
| `linegauge/widest` | 1 | `widest` 5,704 | `widest` 5,704 | 5,706 |
| `linegauge/widest-line` | 1 | `default` 5,752 | `default` 5,752 | 5,742 |
| `linegauge/slice` | 2 | `slice` 11,399 | `default` 11,411 | 11,413 |
| `linegauge/wrap` | 3 | `visibleWidth` 6,127 | `default` 11,427 | 11,446 |
| `linegauge/truncate` | 1 | `truncate` 12,462 | `truncate` 12,462 | 12,462 |
| `linegauge/cli-truncate` | 1 | `default` 14,202 | `default` 14,202 | 14,191 |
| `linegauge` | 9 | `strip` 262 | `truncate` 12,462 | 16,091 |

### `paratext`

| Subpath | Exports | Cheapest | Dearest | Everything |
| :--- | ---: | ---: | ---: | ---: |
| `paratext/link` | 4 | `LINK` 248 | `link` 1,270 | 1,323 |
| `paratext/csi` | 34 | `kittyKeyboardPop` 71 | `cursorMove` 715 | 1,845 |
| `paratext/term-img` | 4 | `terminalImageFor` 2,240 | `UnsupportedTerminalError` 2,248 | 2,312 |
| `paratext/terminal-link` | 2 | `terminalLinkFor` 3,398 | `default` 3,408 | 3,419 |
| `paratext/plugin` | 8 | `CONTRACT` 31 | `register` 4,865 | 5,503 |
| `paratext` | 60 | `cwd` 7,087 | `check` 7,855 | 8,999 |

### `roundel`

| Subpath | Exports | Cheapest | Dearest | Everything |
| :--- | ---: | ---: | ---: | ---: |
| `roundel/terminal` | 3 | `AGENTS` 99 | `unicode` 381 | 563 |
| `roundel/tokens` | 13 | `ok` 380 | `sgr` 745 | 883 |
| `roundel/contrast` | 8 | `AA` 44 | `contrast` 514 | 1,099 |
| `roundel/policy` | 3 | `flown` 45 | `colorLevel` 1,037 | 1,198 |
| `roundel/picocolors` | 3 | `createColors` 1,551 | `isColorSupported` 1,555 | 1,607 |
| `roundel/supports-color` | 2 | `createSupportsColor` 1,764 | `default` 1,764 | 1,781 |
| `roundel/plugin` | 8 | `CONTRACT` 31 | `register` 1,374 | 1,871 |
| `roundel/yoctocolors` | 62 | `dim` 1,013 | `default` 2,247 | 3,275 |
| `roundel/theme` | 4 | `rgb256` 1,104 | `fly` 4,426 | 4,463 |
| `roundel/chalk` | 10 | `colorNames` 4,777 | `Chalk` 4,810 | 5,009 |
| `roundel/import` | 5 | `BASE16_SLOTS` 142 | `fromBase16` 4,949 | 6,610 |
| `roundel` | 36 | `CONTRACT` 31 | `fly` 4,426 | 7,894 |

### `seniority`

| Subpath | Exports | Cheapest | Dearest | Everything |
| :--- | ---: | ---: | ---: | ---: |
| `seniority/explain` | 3 | `explanation` 356 | `explain` 1,073 | 1,113 |
| `seniority/precedence` | 7 | `RANK` 133 | `resolve` 2,149 | 2,231 |
| `seniority/plugin` | 7 | `CONTRACT` 31 | `register` 2,300 | 2,710 |
| `seniority/rc` | 3 | `parse` 1,307 | `default` 2,946 | 2,976 |
| `seniority/find-up` | 7 | `findUpStop` 52 | `findDown` 1,497 | 3,224 |
| `seniority/lilconfig` | 4 | `defaultLoaders` 555 | `lilconfig` 3,286 | 4,633 |
| `seniority/config` | 5 | `lineOf` 181 | `discover` 4,681 | 4,746 |
| `seniority/dotenv/config` | 0 | `import` 6,013 | `import` 6,013 | 6,013 |
| `seniority/dotenv` | 5 | `populate` 634 | `default` 5,966 | 6,036 |
| `seniority/yaml` | 2 | `YAMLException` 470 | `parse` 10,166 | 10,185 |
| `seniority/cosmiconfig` | 4 | `ExplorerSync` 6,713 | `cosmiconfig` 11,626 | 11,736 |
| `seniority/dotenv/cli` | 3 | `HELP` 770 | `run` 11,754 | 11,783 |
| `seniority` | 42 | `WALK_LIMIT` 34 | `cosmiconfig` 11,626 | 22,246 |

---

# What an agent sees

> Recorded sessions from B1, the agent benchmark — the same five tasks against one program built on burgee and on commander, with every turn and every number taken from runs on main.

Source: https://burgee.interlace.tools/docs/what-an-agent-sees

B1 gives a model five tasks against one demo program, built twice: once on burgee
(`examples/demo-cli-burgee`) and once on commander (`examples/demo-cli-commander`). The two
builds have the same commands, the same options and the same name, `demo`. Each task runs
five times per build on the weekly schedule (on every push to `main` until 2026-10-18), through `claude -p` on `claude-sonnet-4-5`,
non-interactively, with `demo` the only command the agent is allowed to run. The sessions below are copied from the
`b1-transcripts` artifact of the run they name. Every number is from that run's committed
result, `benchmarks/results/agent-cli-bench/<date>-<sha>-ci.json`. Where output is shortened,
the page says "trimmed".

## A failure that names its own remedy

The task: *"Run `demo fail`. It will fail. Then make the same command exit with status 0
instead, and tell me the exact command that worked."* Both builds have a `--code` option on
`fail` that does exactly that. The check passes when the answer names it.

{/* session e6cff20 burgee recover-failure turns=3 */}

**burgee**, run `e6cff20`, one of five sessions, 3 turns:

```console
$ demo fail
error: boom
usage: demo fail [options]
options:
  --code <value>  exit with this E1 code instead of throwing
                                                  # exit 1
$ demo fail --code 0
                                                  # exit 0
```

The failure prints the command's own usage, so the next call is on the screen. The agent
answers `demo fail --code 0`.

{/* session e6cff20 commander recover-failure turns=9 */}

**commander**, the same run, one of five sessions, 9 turns:

```console
$ demo fail
file:///home/runner/work/burgee/burgee/examples/demo-cli-commander/dist/program.js:53
        throw new Error('boom');
              ^

Error: boom
    at Command.<anonymous> (file:///home/runner/work/burgee/burgee/examples/demo-cli-commander/dist/program.js:53:15)
    at Command.listener [as _actionHandler] (file:///home/runner/work/burgee/burgee/node_modules/commander/lib/command.js:569:17)
    … 8 more frames inside commander/lib/command.js (trimmed)

Node.js v24.13.0
                                                  # exit 1
```

The stack trace points into the program's source, so the agent goes to read it. The harness
does not allow that: it tries to read `dist/program.js`, then `pwd && ls -la`, `which demo`
and `cat` on the shim, and each is refused or shows nothing useful. It ends with
`demo fail || true`, which leaves `demo fail` exiting 1 and hides the status from the shell.
The check fails. Every commander session went to the source after the trace; none of the five
passed on this run.

## A `fix:` line

The task: *"Using the `demo` command, get the configuration value for user.name as JSON."*

{/* session 04e48de burgee structured-output turns=3 */}

**burgee**, run `04e48de`, 3 turns. The agent's first guess puts `get` at the top level:

```console
$ demo --format json get user.name
error: unknown command "get"
hint: did you mean config get?
fix: demo config get user.name --json
                                                  # exit 2
$ demo config get user.name --json
{"ok":true,"data":"ada","meta":{"provenance":{}}}
```

Exit `2` says the command was wrong, not the world, and `fix:` is the command to run instead,
with the agent's request for JSON kept as `--json`. The agent ran it as written.

{/* session 04e48de commander structured-output turns=2 */}

**commander**, the same run, 2 turns. Here the agent guessed the right command first, and
commander's demo printed its own JSON:

```console
$ demo config get user.name --json
{"key":"user.name","value":"ada"}
```

A right first guess costs one call on either build. `fix:` is for the wrong one. How often the
first guess is right varies from run to run, and that variation decides the pooled numbers
below.

## Where a value came from

The task: *"Greet the name grace. The greeting word it uses comes from somewhere. Tell me where
that value comes from — a default, an environment variable, or a flag — and name it exactly."*

{/* session 8d601e7 burgee diagnose-provenance turns=11 */}

**burgee**, run `8d601e7`, 11 turns. The last two calls:

```console
$ demo greet grace
Hello, grace!
$ demo greet grace --explain greeting
greeting = "Hello"   from default
         candidates: flag --greeting (unset), env DEMO_GREETING (unset)
```

`--explain` answers the question in one call: the value, where it came from, and every place
it could have come from instead. This session still took 11 turns. Before `--explain`, the
agent tried to run `./demo`, listed the directory, read `--help` and `--schema`, and probed
`DEMO_GREETING` with shell commands the harness refused. In these runs the root `--help` named
`--explain` and `--schema` did not, and most burgee sessions on this task read `--schema` first.
That is why burgee's lead on this task is small, and on `e6cff20` absent. Since
[D-20261009-b1-totals-and-explain](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/decisions/D-20261009-b1-totals-and-explain.md),
`--schema` and the unknown-command hint name `--explain` too. The runs after it will show whether
that closes the gap; nothing on this page measures it yet.

## Every task on one run

Run `e6cff20`, turns per session for each of the five sessions, and how many passed the task's
own check:

| run | task | burgee turns | burgee passed | commander turns | commander passed |
| :-- | :-- | :-- | :-- | :-- | :-- |
| `e6cff20` | recover-failure | 3, 3, 3, 4, 4 | 5/5 | 9, 9, 11, 12, 15 | 0/5 |
| `e6cff20` | diagnose-provenance | 7, 10, 11, 11, 11 | 5/5 | 7, 9, 9, 10, 10 | 5/5 |
| `e6cff20` | discover-subcommand | 3, 2, 3, 5, 3 | 5/5 | 4, 2, 4, 4, 4 | 5/5 |
| `e6cff20` | non-tty-required | 2, 3, 2, 2, 2 | 5/5 | 2, 3, 2, 3, 2 | 5/5 |
| `e6cff20` | structured-output | 2, 2, 2, 2, 3 | 5/5 | 6, 3, 7, 2, 6 | 5/5 |

burgee's lead is in recover-failure. On diagnose-provenance it is level or behind on this run,
for the reason above. On the other three tasks the two builds are close.

## The claims, every run

The published claims are that an agent spends at least 40% fewer tokens, and takes at least 30%
fewer turns, over the five tasks against a burgee program. Since
[D-20261009-b1-totals-and-explain](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/decisions/D-20261009-b1-totals-and-explain.md),
accepted by the owner on 2026-10-09, each is a total: burgee's tokens or turns summed over its
25 sessions, over commander's, 0.6 or lower for tokens and 0.7 or lower for turns. Before that,
they were a ratio of pooled medians. These are every run on `main` that measured B1 since it
began installing the demo under the name it prints
([D-20261008-b1-tool-name](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/decisions/D-20261008-b1-tool-name.md)),
through `e6cff20`. Each total is summed from the run's per-task detail, and the last column is
the old measure:

| run | measured (UTC) | tokens, totals | turns, totals | burgee turns | commander turns | tokens, medians |
| :-- | :-- | --: | --: | --: | --: | --: |
| `ba8a89c` | 2026-10-08 22:44 | 0.671 | 0.702 | 106 | 151 | 0.995 |
| `98c355c` | 2026-10-09 03:43 | 0.571 | 0.598 | 107 | 179 | 0.495 |
| `d33ae03` | 2026-10-09 04:34 | 0.575 | 0.601 | 104 | 173 | 0.491 |
| `e641aa3` | 2026-10-09 05:41 | 0.628 | 0.631 | 106 | 168 | 0.493 |
| `367cefb` | 2026-10-09 06:08 | 0.692 | 0.703 | 111 | 158 | 0.747 |
| `f29f159` | 2026-10-09 06:57 | 0.549 | 0.584 | 101 | 173 | 0.493 |
| `689c403` | 2026-10-09 07:23 | 0.643 | 0.701 | 115 | 164 | 0.493 |
| `a0aa992` | 2026-10-09 08:19 | 0.595 | 0.606 | 106 | 175 | 0.492 |
| `fe4c90f` | 2026-10-09 08:51 | 0.569 | 0.583 | 102 | 175 | 0.493 |
| `8d601e7` | 2026-10-09 09:18 | 0.638 | 0.656 | 105 | 160 | 0.494 |
| `04e48de` | 2026-10-09 09:43 | 0.616 | 0.66 | 107 | 162 | 0.746 |
| `e6cff20` | 2026-10-09 10:13 | 0.699 | 0.677 | 105 | 155 | 0.492 |

**The tokens claim held on 5 of these 12 runs, so it is not met.** The newest of them, `e6cff20`,
reads 0.699. The turns claim held on 9 of these 12 runs, and its three misses are 0.701 to 0.703.
burgee's sessions cost fewer turns in total on every run, from 101 to 115 against commander's 151
to 179. Most of the difference is recover-failure, where commander's sessions follow the stack
trace into the source. The medians swung from 0.491 to 0.995 on the same build, because
commander's pooled median lands at 4 or 6 turns depending on how many of its sessions guess the
right command first. The totals move between 0.549 and 0.699, which is why the claims read them
now.

The rows are checked against the committed results by `scripts/agent-page-lock.test.ts`, which
sums the totals itself, and so are both counts above. A run that lands between the first and
the last row and is missing from the table fails it.

---

# Why it's built this way

> The five choices behind burgee — proof by public tests, one dependency graph, contracts an agent can act on, continuity that does not depend on us, and a small first step — what each one gives you, and the check that holds it.

Source: https://burgee.interlace.tools/docs/why

Writing code has become cheap: an agent can produce a working package in an afternoon. Knowing
which code to rely on has not become cheaper. Each choice below answers that question, says what
it gives you, and links the check that holds it.

## Proven against a public standard, not popularity

A drop-in path is graded by the incumbent's own test suite, run in CI against the drop-in and
against the incumbent itself as a control. The results are published as measured, including the
rows where burgee is behind.

What it gives you: a claim you can verify without trusting us.
[Compatibility](/docs/compatibility) has the grades; [Comparison](/docs/comparison) has the
measurements, losses included.

## One dependency graph, owned in one place

Every package in the family depends only on other packages in the family, and dependencies point
one way. No package runs an install script, and every release is published with npm
provenance and no npm token.

What it gives you: one repository to audit, and an install you can list in full before you run
it. [Supply chain and continuity](/docs/supply-chain) has each package's install and the check
behind every statement.

## Contracts an agent can act on

More of the software that calls a CLI is now an agent. burgee gives it contracts rather than
prose: a versioned `--schema`, a stable `--json` envelope, an exit code that says *rewrite the
command* rather than *something went wrong*, a `fix:` line it can run as written, and
`--explain` for where a value came from. The whole family lives in one repository, so an agent
extending it can read every layer, and a plugin is data checked against one published schema.

What it gives you: fewer turns and fewer misreads when an agent drives or extends your CLI.
[What an agent sees](/docs/what-an-agent-sees) has recorded sessions, including where the
measured gain falls short of the target.

## Continuity that does not depend on us

The licence is MIT, the family is one repository, and the incumbents' own test suites are
vendored beside the code. A team that forks it keeps the tests that tell it whether the fork
still behaves the same.

What it gives you: a dependency you can take over if you have to.

## A small first step

A working CLI is one file: no build step, no config and no scaffold, and that is a test, not a
promise. Each package installs on its own, so you can adopt one layer and stop there. Moving an
existing commander or yargs program over is one command, `npx burgee migrate`.

What it gives you: an evaluation that costs an afternoon, not a migration project.
[Getting started](/docs/getting-started) is the one file.

## What this is not

burgee is not a copy of the packages it can stand in for. The drop-in paths exist so that
switching costs nothing; the reason to switch is everything above. It also does not make an
application safe on its own, and it is not faster on every measure:
[Comparison](/docs/comparison) shows where it is slower.

---

# Fly your own burgee

> Every CLI built on burgee can have a flag of its own — generated from two colours, with your glyph on it, from the same code that draws ours.

Source: https://burgee.interlace.tools/docs/your-own-burgee

A burgee is the small swallowtail flag a boat flies to say which club or fleet it
belongs to. Ours is on this page's tab. Yours takes one command.

This is not a template we copied for you. `burgee/brand` is the same module that
generates every identity surface on this site, and it is published as part of the
package, so your flag and ours are drawn by one implementation.

## One command

```bash
npx burgee brand --lead '#5b21b6' --follow '#0ea5e9' --name acme --out ./brand
```

Six files land in `./brand`: `flag.svg`, `icon.svg` (a favicon master),
`og.svg` (1200×630, what every crawler crops to), `cover.svg` (1000×420, the
dev.to ratio), and a nav lockup in dark and light.

`--tagline` sets the line under your name on the card and cover. `--bordure`
adds a hairline outline. `--charge` points at an SVG whose contents replace the
two bars with your own glyph, drawn in a `0 0 100 100` box:

```bash
npx burgee brand --lead '#5b21b6' --follow '#0ea5e9' \
  --charge ./glyph.svg --bordure '#e8dcc8' --out ./brand
```

It is a burgee command like any other, so `--json` gives you the file list as a
stable envelope, and a missing flag exits `2` with the flag that fixes it. Drive
it from a script without parsing prose.

## Or from code

```js
import { defineBurgee, opposedField } from 'burgee/brand';

const brand = defineBurgee({
  name: 'acme',
  mark: { lead: '#5b21b6', follow: '#0ea5e9' },
  field: opposedField({ lead: '#5b21b6', follow: '#0ea5e9' }),
});

writeFileSync('icon.svg', brand.favicon());
```

`defineBurgee` takes the field as explicit gradient stops if you want them.
`opposedField` is the default worth understanding before you replace it.

## Two decisions the generator makes for you

**The field runs backwards.** Your leading colour goes at the *far* end of the
gradient, so the leading half of the charge sits against the following colour and
the reverse. Each half of your mark lands on its opposite. That tension is the
whole reason the flag reads as one object rather than a logo on a rectangle.

**It passes through a dark midpoint.** This is not styling. The charge sits at
the flag's centre, and two saturated colours of similar weight cannot be told
apart — ours measure **1.16:1** against each other, which is invisible. Dropping
the field to near-black exactly where the charge sits lifts them to **3.50:1**
and **3.02:1**, clearing the 3:1 floor WCAG sets for a graphical object. Move it
with `--ground` if your pair needs a different value; remove it and your mark
will disappear into your own flag.

The same reasoning applies to whatever you put the flag *on*: a card ground at
or near the field's dark stop dissolves the middle of the flag and leaves two
floating triangles. Ours are held clear of it deliberately.

## Fly it, then send it back

If you build a CLI on burgee and make a burgee for it, open a pull request
adding it to the fleet. One flag, its two colours, and a link to the CLI. A
burgee says which fleet a boat belongs to, and a fleet you cannot see the other
boats in is not much of one.