@effected/cli 0.10.0 → 0.11.0

package/index.d.ts

@@ -1,54 +1,2032 @@
-import { Cause, Context, Effect, Layer, LogLevel, Logger, MutableRef, Stdio } from "effect";
-import { CliOutput } from "effect/cli";
+import { Array as Array$1, Cause, Context, Effect, FileSystem, Layer, LogLevel, Logger, MutableRef, Option, Path, Runtime, Schema, Stdio, Terminal } from "effect";
+import { Audience, AudienceKind, ColorLevel, CurrentRuntimeEnv, RuntimeEnv, TerminalEnv } from "@effected/env";
+import { CliError, CliOutput, Command, Flag, Param, Prompt } from "effect/cli";
 import { ConfigValidationError } from "@effected/config-file";
+//#region src/Cancelled.d.ts
+declare const Cancelled_base: Schema.Class<Cancelled, Schema.TaggedStruct<"Cancelled", {
+  readonly reason: Schema.Literals<readonly ["escape", "interrupt"]>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A person backed out of an interactive prompt: they pressed escape, or the
+ * prompt was interrupted.
+ *
+ * @remarks
+ * Exits `130`, the conventional status for a run ended by the user, through
+ * core's own `Runtime.errorExitCode` marker, so `CliRuntime.reportFailures`
+ * keeps it. Its default rendering is one line, `cancelled; nothing written`,
+ * because nothing has been written by the time a prompt is cancelled and a
+ * stack trace would only alarm. A consumer `render` still overrides the line, and can hand off to it: the line is
+ * the error's `message`, so `error.message` and `String(error)` carry it.
+ *
+ * @public
+ */
+export declare class Cancelled extends Cancelled_base {
+  /**
+   * The one line, `cancelled; nothing written`.
+   *
+   * @remarks
+   * A prototype getter, not a field, so it is not part of the encoded form, equality or a JSON dump. Assigning to
+   * it is ignored: a library that rewrites `error.message` (to prefix a context, say) must not make this error throw,
+   * which a getter-only property does in strict mode. The line is fixed.
+   */
+  get message(): string;
+  set message(_value: string);
+  /**
+   * The process exit code: `130`.
+   *
+   * @remarks
+   * A prototype getter rather than an own field, so a JSON or logger dump of the error does not carry the
+   * runtime marker.
+   */
+  get [Runtime.errorExitCode](): number;
+}
+//#endregion
+//#region src/CliAudience.d.ts
+/**
+ * The four parsed audience flags a root command carries once {@link CliAudience.flags} is shared onto it.
+ *
+ * @public
+ */
+interface AudienceFlagInput {
+  /** Every `--audience <kind>` occurrence. */
+  readonly audience: ReadonlyArray<AudienceKind>;
+  /** Every `--human` occurrence. */
+  readonly human: ReadonlyArray<boolean>;
+  /** Every `--agent` occurrence. */
+  readonly agent: ReadonlyArray<boolean>;
+  /** Every `--ci` occurrence. */
+  readonly ci: ReadonlyArray<boolean>;
+}
+/**
+ * Options for {@link CliAudience.flags}.
+ *
+ * @public
+ */
+interface CliAudienceFlagsOptions {
+  /**
+   * Hide all four flags from every help screen. They still parse and resolve; describe them in the root
+   * command's description instead.
+   */
+  readonly hidden?: boolean | undefined;
+}
+/**
+ * Resolves to nothing for a command that carries the four audience flags, and to an unsatisfiable marker otherwise,
+ * so `CliAudience.run` on a root that forgot `Command.withSharedFlags(CliAudience.flags())` does not compile. (A
+ * plain `Input extends AudienceFlagInput` constraint does not do this: `Command` is contravariant in its input, so
+ * a command with no flags still type-checks against it.)
+ *
+ * @public
+ */
+type RequiresAudienceFlags<Input> = [Input] extends [AudienceFlagInput] ? unknown : {
+  readonly "missing shared flags": "pipe the root through Command.withSharedFlags(CliAudience.flags())";
+};
+/**
+ * The audience flags of a CLI: `--audience <human|agent|ci>` and the shorthands `--human`, `--agent`, `--ci`,
+ * resolved into `@effected/env`'s `Audience`.
+ *
+ * @remarks
+ * The one wiring: share the flags on the root command and hand the root to {@link CliAudience.run} (or
+ * {@link CliAudience.runWith}), which resolves the flags from argv before core parses and applies
+ * {@link CliAudience.provide} itself:
+ *
+ * ```ts
+ * const root = Command.make("tool").pipe(
+ *   Command.withSharedFlags(CliAudience.flags()),
+ *   Command.withSubcommands([verify]),
+ * )
+ * NodeRuntime.runMain(
+ *   CliRuntime.main(CliAudience.run(root, { version }), { platform: NodeServices.layer, env: {} }),
+ * )
+ * ```
+ *
+ * Core lists a shared flag in the help of every subcommand, not only at the root: that is upstream (Effect-TS/effect
+ * issue 8642), and `flags({ hidden: true })` is the way to keep them out of help altogether.
+ *
+ * A root that forgot `Command.withSharedFlags(CliAudience.flags())` does not compile. Giving more than one
+ * occurrence across the four flags is a usage error even when they agree; a boolean set to false (`--no-agent`,
+ * `--agent=false`) counts as not given. A bad `--audience` value is core's own parse error. Both exit `64` under
+ * `CliRuntime.main`. A conflicting audience together with `--help` exits `0` and prints help, because core handles
+ * its action flags before the resolver runs.
+ *
+ * A flag decides `CliInteractive` from the audience it names and the terminal facts: `--human` is interactive when
+ * `TerminalEnv` says there is a terminal on stdin and on stdout, even where the environment detected an agent, so a
+ * person running the tool inside an agent can ask for the human experience; in a pipe it still cannot prompt. A
+ * non-human flag (`--agent`, `--ci`, `--audience agent|ci`) turns it off and drops `--wizard`, and switches
+ * diagnostics to NDJSON, for the whole run including the parse step where a fallback prompt fires. Without
+ * `TerminalEnv` in the environment a flag only narrows. `--wizard` follows the decision: a run a flag makes
+ * interactive gets it back where the environment's gate had dropped it, and only there: a consumer's own `builtIns`
+ * without it stay without it.
+ * {@link CliAudience.provide} on its own, the path for a bare `Command.run`, acts only on the subcommand handler,
+ * because core parses the root flags into a local context before any of it is visible.
+ *
+ * @public
+ */
+export declare class CliAudience {
+  private constructor();
+  /**
+   * The four flags, for `Command.withSharedFlags` on the root command.
+   *
+   * @remarks
+   * Each is repeatable, so every occurrence is counted; a boolean given as `false` (`--agent=false`,
+   * `--no-agent`) is not an occurrence. Core lists shared flags in every command's help; pass
+   * `hidden` to remove them from all of them.
+   */
+  static readonly flags: (options?: CliAudienceFlagsOptions) => {
+    readonly audience: Flag.Flag<ReadonlyArray<AudienceKind>>;
+    readonly human: Flag.Flag<ReadonlyArray<boolean>>;
+    readonly agent: Flag.Flag<ReadonlyArray<boolean>>;
+    readonly ci: Flag.Flag<ReadonlyArray<boolean>>;
+  };
+  /**
+   * Resolve the flags before every subcommand handler and re-provide `Audience`.
+   *
+   * @remarks
+   * `CliAudience.run` and `runWith` apply this themselves, so a program run through them never needs it. Use it
+   * directly only with a bare `Command.run`, which leaves a fallback prompt blind to the flags (see the class
+   * remarks).
+   *
+   * A failure report is written outside the run, where the flag is not in force, so only `runWith` and `run` carry
+   * the flag's audience to it; with this on its own the report follows the environment's audience.
+   *
+   * Pipe it onto the composite root, after `withSubcommands`, since a parent's handler does not run when a
+   * subcommand is selected. With exactly one flag the audience is `{ kind, source: "flag" }`; with none the
+   * ambient `Audience` is read and provided back unchanged, so `Audience` stays in the requirement a handler
+   * reading it already has, and is added to a program whose handlers do not read it.
+   */
+  static readonly provide: <const Name extends string, Input extends AudienceFlagInput, ContextInput, E, R>(command: Command.Command<Name, Input, ContextInput, E, R>) => Command.Command<Name, Input, ContextInput, E | CliError.UserError, Exclude<R, Audience> | Audience>;
+  /**
+   * Run a command the way `Command.runWith` does, with the audience flag resolved BEFORE core parses.
+   *
+   * @remarks
+   * It scans `argv` for the four audience flags first, then runs core around a provided `Audience` (when exactly
+   * one is given: `{ kind, source: "flag" }`) and a `CliInteractive` decided from it: `--human` is interactive when
+   * `TerminalEnv` reports a terminal on stdin and stdout and `TERM` is not `dumb` (it can turn prompting on under a detected agent), a
+   * non-human flag or a conflict makes it false. A fallback prompt fires while core parses, earlier than
+   * anything `CliAudience.provide` can reach, so `--agent init` on a terminal would otherwise still prompt. No
+   * flag leaves the ambient values untouched. A conflict still gets core's own usage error, exit `64`, from
+   * `CliAudience.provide`'s resolver.
+   *
+   * @param command - the composite root, with the flags shared and `CliAudience.provide` piped on
+   * @param config - the same `version` and `renderErrors` as core's
+   */
+  static readonly runWith: <const Name extends string, Input, E, R, ContextInput>(command: Command.Command<Name, Input, ContextInput, E, R> & RequiresAudienceFlags<Input>, config: {
+    readonly version: string;
+    readonly renderErrors?: boolean | undefined;
+  }) => ((input: ReadonlyArray<string>) => Effect.Effect<void, Exclude<E | CliError.UserError, Terminal.QuitError> | CliError.CliError, Exclude<R, Audience> | Audience | Command.Environment>);
+  /**
+   * `Command.run` with the audience flag resolved before parsing: reads `Stdio.args` and calls
+   * {@link CliAudience.runWith}.
+   *
+   * @param command - the composite root
+   * @param config - the same `version` and `renderErrors` as core's
+   */
+  static readonly run: <const Name extends string, Input, E, R, ContextInput>(command: Command.Command<Name, Input, ContextInput, E, R> & RequiresAudienceFlags<Input>, config: {
+    readonly version: string;
+    readonly renderErrors?: boolean | undefined;
+  }) => Effect.Effect<void, Exclude<E | CliError.UserError, Terminal.QuitError> | CliError.CliError, Exclude<R, Audience> | Audience | Command.Environment>;
+}
+//#endregion
 //#region src/CliColor.d.ts
 /**
- * Whether a CLI's output should carry ANSI colour, decided once and shared by
- * everything that renders — help text, error output, and any rendered result.
+ * Whether a CLI's output should carry ANSI colour, decided once and shared by
+ * everything that renders — help text, error output, and any rendered result.
+ *
+ * @remarks
+ * The decision is `@effected/env`'s `TerminalEnv.colorLevel("stdout")`, which
+ * follows Node's `getColorDepth` precedence: `FORCE_COLOR` first (`0` or an
+ * unrecognised value forces colour off; an empty value, `1` or `true` force basic colour, `2` 256 colours and
+ * `3` truecolor, even without a terminal), then a non-empty `NO_COLOR` or `NODE_DISABLE_COLORS` and
+ * `TERM=dumb`, then the TTY gate. `FORCE_COLOR` therefore beats `NO_COLOR`.
+ * The environment
+ * is read through the ambient `ConfigProvider`, never `process`, so a test
+ * swaps it with `Effect.provideService(ConfigProvider.ConfigProvider, ...)`;
+ * an ambient `TerminalEnv`, such as `TerminalEnv.layerTest`, answers instead
+ * when one is provided.
+ *
+ * @public
+ */
+export declare class CliColor {
+  private constructor();
+  /**
+   * The decision, for passing to a pure renderer as a plain boolean.
+   *
+   * @public
+   */
+  static readonly enabled: Effect.Effect<boolean, never, Stdio.Stdio>;
+  /**
+   * Core's default `CliOutput.Formatter`, coloured by the same decision as
+   * {@link CliColor.enabled}, so help text, parse errors and rendered
+   * output never disagree on whether colour is on.
+   *
+   * @remarks
+   * `overrides` replaces individual methods of the default formatter — for
+   * example `formatVersion`, to append a "via `<carrier>`" line without
+   * losing the other defaults. Each call mints a fresh layer; bind the
+   * result to a `const` or the decision is re-read every time it is
+   * provided.
+   *
+   * The `never` in its output does not mean it installs nothing.
+   * `CliOutput.Formatter` is a `Context.Reference`, whose key type is
+   * `never`, so this layer sets the formatter reference rather than
+   * providing a service. Every command it is provided to renders with the
+   * formatter it sets, and without it they fall back to core's default
+   * formatter.
+   *
+   * @public
+   */
+  static readonly formatterLayer: (overrides?: Partial<CliOutput.Formatter>) => Layer.Layer<never, never, Stdio.Stdio>;
+}
+//#endregion
+//#region src/Glyphs.d.ts
+/**
+ * The symbols a theme draws with.
+ *
+ * @public
+ */
+interface GlyphSet {
+  /** Which set this is. */
+  readonly kind: "unicode" | "ascii";
+  /** The truncation marker. */
+  readonly ellipsis: string;
+  /** The frames of a spinner, in order. */
+  readonly spinner: ReadonlyArray<string>;
+  /** A list bullet. */
+  readonly bullet: string;
+  /** A directional arrow. */
+  readonly arrow: string;
+  /** The separator between the segments of a breadcrumb or path: one for people, one for agents. */
+  readonly pathSeparator: {
+    readonly human: string;
+    readonly agent: string;
+  };
+  /** How long a spinner frame is shown, in milliseconds. */
+  readonly spinnerIntervalMs: number;
+  /**
+   * The segments a tree is drawn with: `branch` before a child that has later siblings, `last` before the final
+   * child, and `pipe` and `blank` as the indent under each. All four are one width so branches align.
+   */
+  readonly tree: {
+    readonly branch: string;
+    readonly last: string;
+    readonly pipe: string;
+    readonly blank: string;
+  };
+}
+/**
+ * Options for {@link Glyphs.select}.
+ *
+ * @public
+ */
+interface GlyphSelectOptions {
+  /**
+   * `true` is ASCII, `false` is Unicode, and `auto` (the default) is ASCII only when `term` is `dumb`.
+   */
+  readonly ascii?: boolean | "auto" | undefined;
+  /**
+   * The `TERM` value, which only `auto` reads. It is passed in rather than read: this selection is pure, so a
+   * caller with no Effect context (an Ink component) uses it, and `process` is never consulted. Unset is not
+   * `dumb`.
+   */
+  readonly term?: string | undefined;
+}
+/**
+ * The two glyph sets: Unicode, and a plain-ASCII fallback for terminals that cannot draw it.
+ *
+ * @remarks
+ * The sets are shared, so they and their nested values are frozen.
+ *
+ * @public
+ */
+export declare class Glyphs {
+  private constructor();
+  /** Unicode symbols. */
+  static readonly unicode: GlyphSet;
+  /**
+   * Pick a glyph set without a service: the one `CliTheme` uses, as a pure function.
+   *
+   * @remarks
+   * `CliTheme.layer` reads `TERM` through `Config` and calls this, so the two agree. `StreamEnv` carries no
+   * `TERM`, and nothing else in it decides ASCII, so the caller passes `term` when it wants `auto` to mean
+   * something.
+   *
+   * @param options - whether to force ASCII or Unicode, and the `TERM` value `auto` reads
+   */
+  static readonly select: (options?: GlyphSelectOptions) => GlyphSet;
+  /** ASCII-only symbols. */
+  static readonly ascii: GlyphSet;
+}
+//#endregion
+//#region src/Token.d.ts
+/**
+ * A named terminal colour: the eight ANSI colours and their bright variants.
+ *
+ * @remarks
+ * The bright variants are spelled as chalk and Ink spell them (`redBright`, `blackBright`), so a style maps to
+ * either without a rename table. `gray` is chalk's alias for `blackBright`.
+ *
+ * @public
+ */
+type NamedColor = "black" | "red" | "green" | "yellow" | "blue" | "magenta" | "cyan" | "white" | "blackBright" | "redBright" | "greenBright" | "yellowBright" | "blueBright" | "magentaBright" | "cyanBright" | "whiteBright" | "gray";
+/**
+ * A terminal style: an optional foreground colour and text attributes.
+ *
+ * @remarks
+ * A style is data; it carries no escape sequences. `CliTheme.paint` renders it for the terminal's colour
+ * level, and at level `none` rendering is the identity. A hex foreground that is not `#rgb` or `#rrggbb`, and
+ * a name that is not a {@link NamedColor}, is ignored when rendered rather than failing.
+ *
+ * @public
+ */
+interface Style {
+  /** The foreground: a named colour or a `#rrggbb` hex. */
+  readonly fg?: NamedColor | `#${string}`;
+  /** Bold. */
+  readonly bold?: boolean;
+  /** Dim, or faint. */
+  readonly dim?: boolean;
+  /** Italic. */
+  readonly italic?: boolean;
+  /** Underline. */
+  readonly underline?: boolean;
+}
+/**
+ * The semantic tokens a theme resolves to a {@link Style}.
+ *
+ * @public
+ */
+type TokenName = "success" | "failure" | "warning" | "info" | "error" | "muted" | "accent" | "emphasis";
+/**
+ * Constructors for {@link Style} values, and the pure resolution of a token to one.
+ *
+ * @public
+ */
+export declare class Token {
+  private constructor();
+  /**
+   * The default {@link Style} of every token, frozen.
+   *
+   * @remarks
+   * Data, not a service: it is what `CliTheme` starts from, and a renderer with no Effect context (an Ink
+   * component) reads it directly.
+   */
+  static readonly defaults: Readonly<Record<TokenName, Style>>;
+  /**
+   * The style a token or style resolves to, as a pure function: no service, no terminal.
+   *
+   * @remarks
+   * An explicit style resolves to itself. A token name resolves to its override when `overrides` has one, else
+   * its default; a name that is not a token (including an `Object.prototype` member) resolves to the empty
+   * style. This is the same resolution `CliTheme.paint` applies, which is what `StreamTheme.style` reports.
+   *
+   * @param token - a token name or an explicit style
+   * @param overrides - styles that replace the default of a token, as `CliThemeOptions.tokens` does
+   */
+  static readonly resolve: (token: TokenName | Style, overrides?: Partial<Record<TokenName, Style>>) => Style;
+  /**
+   * A foreground from a hex colour.
+   *
+   * @param hex - `#rrggbb` (or `#rgb`)
+   */
+  static readonly hex: (hex: `#${string}`) => Style;
+  /**
+   * A foreground from a named colour.
+   *
+   * @param color - the colour
+   */
+  static readonly named: (color: NamedColor) => Style;
+  /**
+   * A style, as written. Exists so a style reads as a token at a call site.
+   *
+   * @param style - the style
+   */
+  static readonly style: (style: Style) => Style;
+}
+//#endregion
+//#region src/Status.d.ts
+/**
+ * How one status looks: a Unicode glyph, an ASCII fallback, a token and a rank.
+ *
+ * @public
+ */
+interface StatusDef {
+  /** The Unicode glyph. */
+  readonly glyph: string;
+  /** The ASCII fallback, used when the theme's glyphs are ASCII. */
+  readonly ascii: string;
+  /** The semantic token, or an explicit style, the glyph is painted with. */
+  readonly token: TokenName | Style;
+  /** Severity for {@link Status.worst}: the highest rank wins. */
+  readonly rank: number;
+}
+/**
+ * The names of the core vocabulary.
+ *
+ * @public
+ */
+type CoreStatusName = "success" | "failure" | "warning" | "info" | "skip" | "pending";
+/**
+ * An open vocabulary of statuses.
+ *
+ * @remarks
+ * Start from `Status.core` and add your own with `extend`. The names are a type parameter,
+ * so `def` and `worst` reject a name the vocabulary does not have at compile time.
+ *
+ * @example
+ * ```ts
+ * import { Status } from "@effected/cli"
+ *
+ * const vocab = Status.extend({
+ * 	timeout: { glyph: "⏱", ascii: "[time]", token: "warning", rank: 85 },
+ * })
+ * const worst = vocab.worst(["success", "timeout"])
+ * // => "timeout"
+ * ```
+ *
+ * @public
+ */
+export declare class Status<Names extends string> {
+  private readonly defs;
+  private constructor();
+  /** The core vocabulary: success, skip, pending, info, warning and failure, by rank 10, 20, 30, 40, 60, 90. */
+  static readonly core: Status<CoreStatusName>;
+  /**
+   * The core vocabulary plus `extra`; an entry that reuses a core name replaces it.
+   *
+   * @param extra - the statuses to add, by name
+   */
+  static readonly extend: <const Extra extends Record<string, StatusDef>>(extra: Extra) => Status<CoreStatusName | (keyof Extra & string)>;
+  /**
+   * This vocabulary plus `extra`; an entry that reuses a name replaces it.
+   *
+   * @remarks
+   * An entry may replace a core name. Replacing `warning` with a lower rank moves the threshold at which
+   * `CliMessage.status` defaults to stderr for this vocabulary, since that threshold is `warning`'s rank in the
+   * vocabulary it is given.
+   *
+   * @param extra - the statuses to add, by name
+   */
+  extend<const Extra extends Record<string, StatusDef>>(extra: Extra): Status<Names | (keyof Extra & string)>;
+  /**
+   * The definition of a status.
+   *
+   * @remarks
+   * A name the vocabulary does not have is a defect: it throws an `Error` naming it and the names that exist. The
+   * types already reject one, so it is reachable only through a cast.
+   *
+   * @param name - a name in this vocabulary
+   */
+  def(name: Names): StatusDef;
+  /**
+   * The full definition of a status as an immutable snapshot, for a caller that stores it.
+   *
+   * @remarks
+   * `def` answers the vocabulary's own entry. `resolve` answers a frozen copy, so a document node that holds
+   * the definition stays plain data and editing it cannot change the vocabulary. The copy is shallow: a
+   * `token` given as a `Style` keeps its own identity. Throws on an unknown name, as {@link Status.def} does;
+   * storing an empty definition in a document instead would fail far from the cause.
+   *
+   * @param name - a name in this vocabulary
+   */
+  resolve(name: Names): StatusDef;
+  /**
+   * A status's glyph from a glyph set: `def.ascii` for an ASCII set, `def.glyph` otherwise. Unpainted, for a caller
+   * that draws it itself (an Ink tree, a reporter).
+   *
+   * @remarks
+   * Throws on an unknown name, as {@link Status.def} does.
+   *
+   * @param name - a name in this vocabulary
+   * @param glyphs - the glyph set, such as `Glyphs.unicode`, `Glyphs.ascii` or a theme's
+   */
+  glyph(name: Names, glyphs: GlyphSet): string;
+  /**
+   * The status with the highest rank; a tie goes to the one that comes first in `names`.
+   *
+   * @remarks
+   * `rank` is SEVERITY, not an aggregation policy: the higher rank wins, so in `Status.core` a `skip` outranks a
+   * `success`. A consumer whose aggregate differs (a test run where passes dominate skips, say) folds its own
+   * rule over the names instead of reading this.
+   *
+   * Takes at least one name, so the answer is always a name. For an array that may be empty, use
+   * {@link Status.worstOption}. They are two methods because a literal and an array variable are the same
+   * array at runtime, so one method could not return a name for one and an `Option` for the other.
+   *
+   * @param names - the statuses to compare
+   */
+  worst(names: Array$1.NonEmptyReadonlyArray<Names>): Names;
+  /**
+   * The status with the highest rank of an array that may be empty: `None` when it is, otherwise `Some` of
+   * the worst, a tie going to the one that comes first in `names`. Rank is severity, not an aggregation policy; see
+   * {@link Status.worst}.
+   *
+   * @param names - the statuses to compare
+   */
+  worstOption(names: ReadonlyArray<Names>): Option.Option<Names>;
+}
+//#endregion
+//#region src/CliTheme.d.ts
+/**
+ * The shape of the {@link CliTheme} service: a colour level, a glyph set and the functions that use them.
+ *
+ * @remarks
+ * The whole shape is one immutable value with no mockable behaviour, so `Layer.succeed` (via
+ * {@link CliTheme.layerTest}) is the complete double.
+ *
+ * @public
+ */
+interface CliThemeShape extends StreamTheme {
+  /**
+   * The theme of one output stream, painting with THAT stream's colour level.
+   *
+   * @remarks
+   * The members above are the `stdout` ones. Anything written to stderr must be painted through
+   * `forStream("stderr")`: redirecting one stream (`tool 2>err.log`, `tool | jq`) changes that stream's colour
+   * and not the other's.
+   */
+  readonly forStream: (stream: "stdout" | "stderr") => StreamTheme;
+}
+/**
+ * A theme bound to one stream's colour level.
+ *
+ * @public
+ */
+interface StreamTheme {
+  /** Render `text` in a token or an explicit style; the identity when colour is `none`. */
+  readonly paint: (token: TokenName | Style, text: string) => string;
+  /**
+   * The resolved {@link Style} of a token or style: the one `paint` renders, whatever the colour level.
+   *
+   * @remarks
+   * Pure data, for a renderer that is not ANSI (an Ink component maps it to its own props). It applies this
+   * theme's token overrides, so it is `Token.resolve` with them.
+   */
+  readonly style: (token: TokenName | Style) => Style;
+  /** The raw opening SGR sequence of a token or style; `""` when colour is `none`. */
+  readonly sgr: (token: TokenName | Style) => string;
+  /** The glyph set in use. */
+  readonly glyphs: GlyphSet;
+  /** The colour level of the stream. */
+  readonly color: ColorLevel;
+  /** Render a status from a vocabulary: its glyph, painted with its token, then `text` when given. */
+  readonly status: <N extends string>(vocab: Status<N>, name: N, text?: string) => string;
+}
+/**
+ * Options for {@link CliTheme.layer}.
+ *
+ * @public
+ */
+interface CliThemeOptions {
+  /** Styles that replace the default of a token. */
+  readonly tokens?: Partial<Record<TokenName, Style>> | undefined;
+  /** The glyph set. `auto`, the default, is ASCII only when `TERM=dumb`. */
+  readonly glyphs?: "unicode" | "ascii" | "auto" | undefined;
+}
+/**
+ * Options for {@link CliTheme.layerTest}.
+ *
+ * @public
+ */
+interface CliThemeTestOptions {
+  /** The stdout colour level; `none` by default. */
+  readonly color?: ColorLevel | undefined;
+  /** The stderr colour level; the same as `color` by default. */
+  readonly stderrColor?: ColorLevel | undefined;
+  /** The glyph set; Unicode by default. */
+  readonly glyphs?: "unicode" | "ascii" | undefined;
+}
+declare const CliTheme_base: Context.ServiceClass<CliTheme, "@effected/cli/CliTheme", CliThemeShape>;
+/**
+ * The presentation of a CLI: colour tokens, glyphs and statuses, decided once from the terminal.
+ *
+ * @remarks
+ * A `Context.Service`, not a `Reference`. A colour level is a fact about the terminal, not a preference with a
+ * safe default, so there is nothing sensible for an unprovided theme to read; requiring it puts `CliTheme` in
+ * `R` and a program that forgot to wire it fails to compile rather than printing plain text to a colour
+ * terminal. {@link CliTheme.layer} reads `TerminalEnv`.
+ *
+ * @public
+ */
+export declare class CliTheme extends CliTheme_base {
+  /**
+   * The theme for the terminal `TerminalEnv` describes.
+   *
+   * @remarks
+   * Bind the layer to a constant and provide it once. With `glyphs: "auto"` the glyph set is ASCII only when
+   * `TERM=dumb`, read through `Config`.
+   *
+   * @param options - token overrides and the glyph set
+   */
+  static readonly layer: (options?: CliThemeOptions) => Layer.Layer<CliTheme, never, TerminalEnv>;
+  /**
+   * A fixed theme that needs nothing; `none` colour and Unicode glyphs unless told otherwise.
+   *
+   * @param options - the colour level and glyph set
+   */
+  static readonly layerTest: (options?: CliThemeTestOptions) => Layer.Layer<CliTheme>;
+  /**
+   * Sets core's `Prompt.Theme` from the tokens, so built-in prompts match the rest of the output.
+   *
+   * @remarks
+   * The colour fields are raw SGR openers and are empty strings when colour is `none`. Under ASCII glyphs the
+   * prompt symbols fall back to ASCII too. A colourless theme is not byte-clean: core's `Ansi.annotate`
+   * appends a `\x1b[0m` reset, and prompts write cursor and underline codes, whatever the theme says.
+   */
+  static readonly promptTheme: Layer.Layer<never, never, CliTheme>;
+}
+//#endregion
+//#region src/Doc.d.ts
+/**
+ * A status as a document stores it: its name and its resolved definition.
+ *
+ * @remarks
+ * The definition is stored, not the vocabulary, so a node stays plain data.
+ *
+ * @public
+ */
+interface StatusRef {
+  /** The name in the vocabulary it was resolved from. */
+  readonly name: string;
+  /** The resolved definition. */
+  readonly def: StatusDef;
+}
+/**
+ * Where a link points: a URL, or a file with an optional position.
+ *
+ * @public
+ */
+type LinkTarget = {
+  readonly url: string;
+} | {
+  readonly file: string;
+  readonly line?: number;
+  readonly col?: number;
+};
+/**
+ * Content that flows inside a line.
+ *
+ * @remarks
+ * - `Text`: a run of text, optionally painted with a token or style.
+ * - `Code`: code in a monospace span.
+ * - `Link`: a labelled link to a URL or a file position.
+ * - `StatusMark`: a status glyph, carrying its resolved definition.
+ * - `Path`: a path or breadcrumb, joined with the audience's path separator.
+ * - `Strong` and `Emphasis`: content in bold or italic; markdown `**` and `_`.
+ * - `File`: a path shown through the context's `displayPath`, never linked.
+ *
+ * @public
+ */
+type Inline = {
+  readonly _tag: "Text";
+  readonly value: string;
+  readonly token?: TokenName | Style;
+} | {
+  readonly _tag: "Code";
+  readonly value: string;
+} | {
+  readonly _tag: "Link";
+  readonly target: LinkTarget;
+  readonly label: ReadonlyArray<Inline>;
+  /**
+   * Whether plain text (and `ansi` with links off, and markdown with no URL) follows the label with the target in
+   * parentheses. Unset, it does so only when the label does not already show the target's display form.
+   */
+  readonly suffix?: boolean;
+} | {
+  readonly _tag: "StatusMark";
+  readonly name: string;
+  readonly def: StatusDef;
+} | {
+  readonly _tag: "Path";
+  readonly segments: ReadonlyArray<string>;
+} | {
+  readonly _tag: "Strong";
+  readonly content: ReadonlyArray<Inline>;
+} | {
+  readonly _tag: "Emphasis";
+  readonly content: ReadonlyArray<Inline>;
+} | {
+  readonly _tag: "File";
+  readonly path: string;
+};
+/**
+ * A node of a {@link TreeNode} tree: a label and its children.
+ *
+ * @public
+ */
+interface TreeNode {
+  /** What the node says. */
+  readonly label: ReadonlyArray<Inline>;
+  /** Its children, in order. */
+  readonly children: ReadonlyArray<TreeNode>;
+}
+/**
+ * One column of a table.
+ *
+ * @public
+ */
+interface Column {
+  /** The header cell. */
+  readonly header: ReadonlyArray<Inline>;
+  /** How the column's cells align; left when unset. */
+  readonly align?: "left" | "right" | "center";
+}
+/**
+ * One counter of a `Counts` block.
+ *
+ * @public
+ */
+interface Counter {
+  /** A stable identifier, for a caller's total rule. */
+  readonly key: string;
+  /** What the counter is called when shown. */
+  readonly label: string;
+  /** The count. */
+  readonly n: number;
+  /** The status the count is painted with. */
+  readonly status: StatusRef;
+  /** Show the counter when `n` is zero; by default a zero counter is hidden. */
+  readonly showZero?: boolean;
+}
+/**
+ * A block of a document.
+ *
+ * @remarks
+ * - `Paragraph`: one logical line; a paragraph of paragraphs is a `Section`.
+ * - `List` and `Table`: with an optional `cap` on the rows shown, and an `overflow` that says what the hidden rows
+ *   amount to, given how many there are.
+ * - `Tree`: nested labels.
+ * - `Collapsible`: a titled body a renderer may fold.
+ * - `Callout`: a body with a kind.
+ * - `CodeBlock`: preformatted text, with an optional language.
+ * - `Diff`: expected against received text, with an optional cap on the lines shown.
+ * - `Section`: children under an optional title.
+ * - `Counts`: labelled counters in one of three layouts. `total` replaces the default sum of every counter, and
+ *   `durationMs` is how long it took. `share: false` drops the headline's share of the total, and `paint` limits what
+ *   is painted.
+ * - `Verbatim`: lines kept exactly, each indented, never wrapped.
+ * - `CountsTable`: a table of `Counts` rows, a column per counter key, a `duration` column when some row has one, and
+ *   an optional summed total row.
+ * - `Lines`: one line per entry; markdown keeps them apart with hard breaks.
+ * - `Line`: one line, which `truncate` cuts to the width instead of wrapping.
+ * - `DiffText`: a unified diff, as given; `truncate` cuts each line to the width.
+ * - A `List` may be `compact`, with no blank lines between an item's children (a blank line of an item's own content
+ *   keeps the item's indent in plain and `ansi`), and a `Table` may be `style: "pipe"`.
+ * - `Annotation`: a GitHub Actions annotation, which only `Render.githubLog` writes.
+ *
+ * Nodes are plain data and nothing decodes them, so a function field such as `overflow` or `total` is fine.
+ *
+ * @public
+ */
+type Block = {
+  readonly _tag: "Heading";
+  readonly level: 1 | 2 | 3 | 4;
+  readonly content: ReadonlyArray<Inline>;
+} | {
+  readonly _tag: "Paragraph";
+  readonly content: ReadonlyArray<Inline>;
+} | {
+  readonly _tag: "List";
+  readonly items: ReadonlyArray<Block>;
+  readonly cap?: number;
+  readonly overflow?: (hidden: number) => ReadonlyArray<Inline>;
+  readonly compact?: boolean;
+} | {
+  readonly _tag: "Table";
+  readonly columns: ReadonlyArray<Column>;
+  readonly rows: ReadonlyArray<ReadonlyArray<ReadonlyArray<Inline>>>;
+  readonly cap?: number;
+  readonly overflow?: (hidden: number) => ReadonlyArray<Inline>;
+  readonly style?: "pipe";
+} | {
+  readonly _tag: "Tree";
+  readonly root: TreeNode;
+} | {
+  readonly _tag: "Collapsible";
+  readonly title: ReadonlyArray<Inline>;
+  readonly body: ReadonlyArray<Block>;
+  readonly open?: boolean;
+} | {
+  readonly _tag: "Callout";
+  readonly kind: "note" | "tip" | "important" | "warning" | "caution";
+  readonly body: ReadonlyArray<Block>;
+} | {
+  readonly _tag: "CodeBlock";
+  readonly lang?: string;
+  readonly text: string;
+} | {
+  readonly _tag: "Diff";
+  readonly expected: string;
+  readonly received: string;
+  readonly cap?: number;
+} | {
+  readonly _tag: "Section";
+  readonly title?: ReadonlyArray<Inline>;
+  readonly children: ReadonlyArray<Block>;
+} | {
+  readonly _tag: "Counts";
+  readonly label?: ReadonlyArray<Inline>;
+  readonly counters: ReadonlyArray<Counter>;
+  readonly total?: (counters: ReadonlyArray<Counter>) => number;
+  readonly qualifier?: ReadonlyArray<Inline>;
+  readonly durationMs?: number;
+  readonly layout: "inline" | "columns" | "row";
+  readonly share?: boolean;
+  readonly paint?: "all" | "glyph" | "none";
+  readonly suffix?: ReadonlyArray<Inline>;
+} | {
+  readonly _tag: "CountsTable";
+  readonly rows: ReadonlyArray<CountsRow>;
+  readonly totalRow?: boolean | ReadonlyArray<Inline>;
+  readonly labelHeader?: ReadonlyArray<Inline>;
+  readonly durationHeader?: ReadonlyArray<Inline>;
+} | {
+  readonly _tag: "Lines";
+  readonly lines: ReadonlyArray<ReadonlyArray<Inline>>;
+} | {
+  readonly _tag: "Line";
+  readonly content: ReadonlyArray<Inline>;
+  readonly truncate?: boolean;
+} | {
+  readonly _tag: "DiffText";
+  readonly text: string;
+  readonly cap?: number;
+  readonly truncate?: boolean;
+} | {
+  readonly _tag: "Verbatim";
+  readonly text: string;
+  readonly indent?: number;
+} | ({
+  readonly _tag: "Annotation";
+  readonly message: string;
+} & AnnotationOptions);
+/**
+ * Where and how a GitHub Actions annotation is shown: its level, and an optional position and title.
+ *
+ * @public
+ */
+interface AnnotationOptions {
+  /** `error`, `warning` or `notice`. */
+  readonly level: "error" | "warning" | "notice";
+  /** The file it points at, as the runner should show it (relative to the workspace). */
+  readonly file?: string;
+  /** The line it starts on. */
+  readonly line?: number;
+  /** The column it starts at. */
+  readonly col?: number;
+  /** The line it ends on. */
+  readonly endLine?: number;
+  /** The column it ends at. */
+  readonly endColumn?: number;
+  /** Its title. */
+  readonly title?: string;
+}
+/**
+ * One row of a `CountsTable`: its label, its counters and how long it took.
+ *
+ * @public
+ */
+interface CountsRow {
+  /** What the row is, such as a project name. */
+  readonly label: ReadonlyArray<Inline>;
+  /** Its counters; their keys pick the column each lands in. */
+  readonly counters: ReadonlyArray<Counter>;
+  /** How long it took, in milliseconds, shown with `Fmt.duration` in the duration column. */
+  readonly durationMs?: number;
+}
+/**
+ * The options of {@link Doc.countsTable}.
+ *
+ * @public
+ */
+interface CountsTableOptions {
+  /** A last row summing each column: labelled with a plain `Total` when `true`, or with the content given (`Doc.strong("Total")` for a bold one). */
+  readonly totalRow?: boolean | InlineInput;
+  /** The header of the label column, such as `Project`; empty when unset. */
+  readonly labelHeader?: InlineInput;
+  /** The header of the duration column, shown only when some row has a `durationMs`; `duration` when unset. */
+  readonly durationHeader?: InlineInput;
+}
+/**
+ * Options for {@link Doc.list}.
+ *
+ * @public
+ */
+interface ListOptions extends OverflowOptions {
+  /** No blank lines between the children of an item, such as a section's title and body. */
+  readonly compact?: boolean;
+}
+/**
+ * Options for {@link Doc.table}.
+ *
+ * @public
+ */
+interface TableOptions extends OverflowOptions {
+  /**
+   * `pipe` gives plain and `ansi` istanbul's shape: rules above and below the header and at the end, cells joined
+   * with ` | `. Markdown's table is a pipe table either way. Unset, the columns are space-aligned.
+   */
+  readonly style?: "pipe";
+}
+/**
+ * Options for `Doc.link`.
+ *
+ * @public
+ */
+interface LinkOptions {
+  /**
+   * Whether the target follows the label in parentheses where a link cannot be followed: plain text, `ansi` with
+   * links off, markdown with no URL. `true` always, `false` never; unset, only when the label does not already show
+   * the target's display form (`displayPath(file)`, then `:line` and `:col` when present).
+   */
+  readonly suffix?: boolean;
+}
+/**
+ * A whole document: its blocks, in order.
+ *
+ * @public
+ */
+type Document = ReadonlyArray<Block>;
+/**
+ * What a constructor accepts for content: a string, one `Inline`, or an array of either.
+ *
+ * @remarks
+ * A string becomes a `Text` node with no token.
+ *
+ * @public
+ */
+type InlineInput = string | Inline | ReadonlyArray<string | Inline>;
+/**
+ * A tree node as a constructor accepts it: the label may be a string and `children` may be left out.
+ *
+ * @public
+ */
+interface TreeInput {
+  /** What the node says. */
+  readonly label: InlineInput;
+  /** Its children; none when omitted. */
+  readonly children?: ReadonlyArray<TreeInput>;
+}
+/**
+ * The inline node with a given `_tag`, so a constructor can return its precise type.
+ *
+ * @public
+ */
+type InlineOf<Tag extends Inline["_tag"]> = Extract<Inline, {
+  readonly _tag: Tag;
+}>;
+/**
+ * The block node with a given `_tag`, so a constructor can return its precise type.
+ *
+ * @public
+ */
+type BlockOf<Tag extends Block["_tag"]> = Extract<Block, {
+  readonly _tag: Tag;
+}>;
+/**
+ * The cap and overflow options of a list or table.
+ *
+ * @public
+ */
+interface OverflowOptions {
+  /** The most rows to show; the renderer hides the rest. */
+  readonly cap?: number;
+  /** Says what the hidden rows amount to, given how many there are; it is a function and is never serialised. */
+  readonly overflow?: (hidden: number) => InlineInput;
+}
+/**
+ * The options of {@link Doc.counts}.
+ *
+ * @public
+ */
+interface CountsOptions {
+  /** A leading label. */
+  readonly label?: InlineInput;
+  /** The counters, in the order they are shown. */
+  readonly counters: ReadonlyArray<Counter>;
+  /** Replaces the default total, the sum of `n` over every counter, for example to fold timed-out runs in. */
+  readonly total?: (counters: ReadonlyArray<Counter>) => number;
+  /** Text after the counters, such as `(1 flaky)`. */
+  readonly qualifier?: InlineInput;
+  /** How long it took, in milliseconds. */
+  readonly durationMs?: number;
+  /** How the counters are laid out. */
+  readonly layout: "inline" | "columns" | "row";
+  /** Whether the first counter shows its share of the total, `n/total`; `true` by default. `false` shows `n label`. */
+  readonly share?: boolean;
+  /**
+   * What is painted: `all` (the default) paints the counters, the label, the qualifier and the duration; `glyph`
+   * paints only a status glyph, if one is shown; `none` paints nothing.
+   */
+  readonly paint?: "all" | "glyph" | "none";
+  /** Text after the duration, such as `across 3 files`. */
+  readonly suffix?: InlineInput;
+}
+/**
+ * Options for {@link Doc.print}.
+ *
+ * @public
+ */
+interface DocPrintOptions {
+  /** The stream to write to; `stdout` by default. */
+  readonly stream?: "stdout" | "stderr" | undefined;
+  /**
+   * The renderer. `auto`, the default, is chosen from the audience: `plain` for an agent, `githubLog` for a CI
+   * that `CurrentRuntimeEnv` says is GitHub Actions and `plain` for any other, and `ansi` for a human.
+   */
+  readonly format?: "auto" | "plain" | "ansi" | "markdown" | "githubLog" | undefined;
+  /** Turns an absolute path into its display form, for example relative to the workspace; see `Render.context`. */
+  readonly displayPath?: ((absolute: string) => string) | undefined;
+  /** The display columns to lay out at, replacing the audience's default; see `Render.context`. */
+  readonly width?: number | undefined;
+}
+/**
+ * Constructors for the document IR, and two helpers a renderer shares.
+ *
+ * @remarks
+ * Every constructor returns a frozen node and copies the arrays it is given, so editing an input afterwards
+ * cannot change a document. An optional field that is not given is absent from the node, not `undefined`.
+ * Content arguments accept a string, an `Inline` or an array of either.
+ *
+ * A node is plain data: nothing decodes or encodes one, so a function field such as `overflow` or `total` is fine
+ * and a document is not meant to be serialised.
+ *
+ * Freezing covers what a `Doc` constructor builds. A literal you write by hand is not frozen, and a `Style` object
+ * given as a token is shared by reference (the freeze of a status definition is shallow for the same reason).
+ *
+ * @example
+ * ```ts
+ * import { Doc, Status } from "@effected/cli"
+ *
+ * const report = [
+ * 	Doc.heading(2, "Results"),
+ * 	Doc.paragraph(Doc.status(Status.core, "success"), " ", "3 checks passed"),
+ * 	Doc.table([{ header: "Check" }, { header: "Time", align: "right" }], [["lint", "1.2s"]]),
+ * ]
+ * // Written for whoever is reading: `yield* Doc.print(report)`
+ * ```
+ *
+ * @public
+ */
+export declare class Doc {
+  private constructor();
+  /**
+   * A run of text.
+   *
+   * @param value - the text
+   * @param token - a semantic token or a style to paint it with
+   */
+  static text(value: string, token?: TokenName | Style): InlineOf<"Text">;
+  /**
+   * Code in a monospace span.
+   *
+   * @param value - the code
+   */
+  static code(value: string): InlineOf<"Code">;
+  /**
+   * A link to a URL or a file position.
+   *
+   * @param target - `{ url }` or `{ file, line?, col? }`
+   * @param label - what the link says; when omitted, the bare URL or file path, which leaves out `line` and `col`
+   * @param options - `suffix`, whether the target follows the label where the link cannot be followed
+   */
+  static link(target: LinkTarget, label?: InlineInput, options?: LinkOptions): InlineOf<"Link">;
+  /**
+   * A link when there is a target, and its label alone when there is none: a string label as a `Text`, any other
+   * inline as itself.
+   *
+   * @param target - `{ url }`, `{ file, line?, col? }`, or `undefined` for no link
+   * @param label - what the link says
+   * @param options - `suffix`, whether the target follows the label where the link cannot be followed
+   */
+  static link(target: LinkTarget | undefined, label: string | Inline, options?: LinkOptions): Inline;
+  /**
+   * A status glyph, holding the resolved definition.
+   *
+   * @remarks
+   * A name the vocabulary does not have is a compile error.
+   *
+   * @param vocab - the vocabulary the name belongs to
+   * @param name - a status name in it
+   */
+  static status<N extends string>(vocab: Status<N>, name: NoInfer<N>): InlineOf<"StatusMark">;
+  /**
+   * Content in bold: markdown `**…**`, bold in `ansi`, and the content as is in plain and `githubLog`.
+   *
+   * @param content - any number of strings, inlines or arrays of them, in order
+   */
+  static strong(...content: Array<InlineInput>): InlineOf<"Strong">;
+  /**
+   * Content in italic: markdown `*…*` (which GFM reads inside a word too), italic in `ansi`, and the content as is in
+   * plain and `githubLog`.
+   *
+   * @param content - any number of strings, inlines or arrays of them, in order
+   */
+  static em(...content: Array<InlineInput>): InlineOf<"Emphasis">;
+  /**
+   * A file path, shown through the context's `displayPath` and never linked.
+   *
+   * @param path - the path, usually absolute
+   */
+  static file(path: string): InlineOf<"File">;
+  /**
+   * A path or breadcrumb; a renderer joins the segments with the audience's separator.
+   *
+   * @param segments - the segments, in order
+   */
+  static path(...segments: Array<string>): InlineOf<"Path">;
+  /**
+   * A heading.
+   *
+   * @param level - 1 to 4
+   * @param content - the heading text
+   */
+  static heading(level: 1 | 2 | 3 | 4, content: InlineInput): BlockOf<"Heading">;
+  /**
+   * One logical line of content.
+   *
+   * @param content - any number of strings, inlines or arrays of them, in order
+   */
+  static paragraph(...content: Array<InlineInput>): BlockOf<"Paragraph">;
+  /**
+   * A list of blocks.
+   *
+   * @param items - the items
+   * @param options - `cap`, `overflow`, and `compact` for no blank lines inside an item
+   */
+  static list(items: ReadonlyArray<Block>, options?: ListOptions): BlockOf<"List">;
+  /**
+   * A table.
+   *
+   * @param columns - the columns: a header and an optional alignment each
+   * @param rows - the rows; each cell takes a string, an inline or an array of either
+   * @param options - `cap`, `overflow`, and `style: "pipe"` for istanbul's shape in plain and `ansi`
+   */
+  static table(columns: ReadonlyArray<{
+    readonly header: InlineInput;
+    readonly align?: "left" | "right" | "center";
+  }>, rows: ReadonlyArray<ReadonlyArray<InlineInput>>, options?: TableOptions): BlockOf<"Table">;
+  /**
+   * A tree of labels.
+   *
+   * @param root - the root; a node's `children` may be left out
+   */
+  static tree(root: TreeInput): BlockOf<"Tree">;
+  /**
+   * A titled body a renderer may fold.
+   *
+   * @param title - the title
+   * @param body - the body
+   * @param options - `open` asks for it to start unfolded
+   */
+  static collapsible(title: InlineInput, body: ReadonlyArray<Block>, options?: {
+    readonly open?: boolean;
+  }): BlockOf<"Collapsible">;
+  /**
+   * A callout.
+   *
+   * @param kind - `note`, `tip`, `important`, `warning` or `caution`
+   * @param body - the body
+   */
+  static callout(kind: "note" | "tip" | "important" | "warning" | "caution", body: ReadonlyArray<Block>): BlockOf<"Callout">;
+  /**
+   * Preformatted text.
+   *
+   * @param text - the text
+   * @param lang - its language, for a renderer that fences it
+   */
+  static codeBlock(text: string, lang?: string): BlockOf<"CodeBlock">;
+  /**
+   * Expected against received text.
+   *
+   * @param expected - the expected text
+   * @param received - the received text
+   * @param options - `cap` limits the lines shown
+   */
+  static diff(expected: string, received: string, options?: {
+    readonly cap?: number;
+  }): BlockOf<"Diff">;
+  /**
+   * Children under an optional title.
+   *
+   * @param title - the title, or `undefined` for none
+   * @param children - the blocks
+   */
+  static section(title: InlineInput | undefined, children: ReadonlyArray<Block>): BlockOf<"Section">;
+  /**
+   * One counter of a `Counts` block, with its status definition resolved.
+   *
+   * @remarks
+   * A name the vocabulary does not have is a compile error.
+   *
+   * @param vocab - the vocabulary the status belongs to
+   * @param name - a status name in it
+   * @param options - the counter's `key`, `label` and count `n`, and `showZero` to keep it when `n` is zero
+   */
+  static counter<N extends string>(vocab: Status<N>, name: NoInfer<N>, options: {
+    readonly key: string;
+    readonly label: string;
+    readonly n: number;
+    readonly showZero?: boolean;
+  }): Counter;
+  /**
+   * Counters in one of three layouts.
+   *
+   * @param options - the counters, the layout and the optional label, total rule, qualifier and duration
+   */
+  static counts(options: CountsOptions): BlockOf<"Counts">;
+  /**
+   * Counters as a table: a row per entry, a column per counter key (in the order the keys first appear, headed by
+   * the counter's label), and an optional total row summing each column.
+   *
+   * @remarks
+   * A row without a counter for some key leaves that cell empty, and it counts as zero in the total. A counter whose
+   * `n` is zero shows `0`, as a `Doc.table` cell would: a counter's `showZero` has no effect in a table, only in a
+   * `Counts` block, so there is no need to set it. `totalRow`
+   * labels the total row with a plain `Total` when `true`, or with the content given: for a bold one, pass
+   * `totalRow: Doc.strong("Total")`. A column is headed by its counter's `label`; a counter's status paints its cells
+   * in `ansi` and is ignored in markdown, so a plain numbers table may pass any status. `labelHeader` heads the label column, which
+   * is otherwise empty. When some row has a `durationMs`, a last column shows it with `Fmt.duration`, headed
+   * `durationHeader` (`duration` by default); a row without one has an empty cell there and counts as zero in the
+   * total row's summed duration.
+   *
+   * @param rows - each row's label, counters and optional duration
+   * @param options - `totalRow`, to add the summed row; the label and duration column headers
+   */
+  static countsTable(rows: ReadonlyArray<{
+    readonly label: InlineInput;
+    readonly counters: ReadonlyArray<Counter>;
+    readonly durationMs?: number;
+  }>, options?: CountsTableOptions): BlockOf<"CountsTable">;
+  /**
+   * Lines, one per entry, in every renderer: markdown joins them with hard breaks so they never collapse into one.
+   *
+   * @param lines - the entries; each takes a string, an inline or an array of either
+   */
+  static lines(lines: ReadonlyArray<InlineInput>): BlockOf<"Lines">;
+  /**
+   * One line of content; with `truncate`, it is cut to the width with the glyph set's ellipsis instead of wrapping.
+   *
+   * @remarks
+   * Without `truncate` a line longer than the width wraps. For a single line that must never wrap nor be cut, such
+   * as a test's full name used as a title, use {@link Doc.verbatim}.
+   *
+   * @param content - the line
+   * @param options - `truncate`
+   */
+  static line(content: InlineInput, options?: {
+    readonly truncate?: boolean;
+  }): BlockOf<"Line">;
+  /**
+   * A unified diff as given, such as a test runner's: sanitized, its `+` and `-` lines painted `success` and
+   * `failure` in `ansi`, and a `diff` fence in markdown.
+   *
+   * @remarks
+   * With `truncate`, plain and `ansi` cut each line to the width with the glyph set's ellipsis instead of wrapping
+   * it; an agent's or a CI's width is unbounded, so nothing is cut for them unless the context gives a finite width.
+   * Markdown keeps every line whole. Inside a compact list item a blank line of the diff keeps the item's indent.
+   *
+   * A trailing line break ends the last line, as in a unified diff file, and adds no blank line after it: `"a\n"` is
+   * one line. To end on a blank line, end the text with two line breaks.
+   *
+   * @param unified - the diff
+   * @param options - `cap`, the most lines shown; `truncate`, to cut each line to the width
+   */
+  static diffText(unified: string, options?: {
+    readonly cap?: number;
+    readonly truncate?: boolean;
+  }): BlockOf<"DiffText">;
+  /**
+   * Lines kept exactly: each indented by `indent` spaces, sanitized, and never wrapped.
+   *
+   * @remarks
+   * Plain, `ansi` and `githubLog` write the lines as they are; markdown fences them, so the indentation survives.
+   *
+   * It is the tool for a single line that must never wrap nor be cut, whatever the width: {@link Doc.line} wraps at
+   * the width, or cuts with `truncate`, and `verbatim` does neither.
+   *
+   * @param text - the lines
+   * @param options - `indent`, the spaces in front of every line; none by default
+   */
+  static verbatim(text: string, options?: {
+    readonly indent?: number;
+  }): BlockOf<"Verbatim">;
+  /**
+   * A GitHub Actions annotation: `Render.githubLog` writes it as one workflow command (`::error file=…::message`),
+   * and every other renderer writes nothing.
+   *
+   * @remarks
+   * It is the kit's own command, so `githubLog` does not neutralize it; its message and properties are escaped, so
+   * no text in them can end the command or start another. It is a command where a line starts: at the top level, as a
+   * top-level section's child, or as a direct child of a group's body. Nested deeper, it is dropped.
+   *
+   * @param options - the level, and the optional file, position and title
+   * @param message - what it says
+   */
+  static annotation(options: AnnotationOptions, message: string): BlockOf<"Annotation">;
+  /**
+   * The total of a `Counts` block: the caller's rule when it has one, otherwise the sum of `n` over every counter.
+   *
+   * @remarks
+   * The rule sees every counter, including the ones a renderer hides, so hiding never changes the total.
+   *
+   * @param block - the `Counts` block
+   */
+  static total(block: BlockOf<"Counts">): number;
+  /**
+   * The counters a renderer shows: every one except a zero counter that does not ask for `showZero`.
+   *
+   * @param block - the `Counts` block
+   */
+  static visibleCounters(block: BlockOf<"Counts">): ReadonlyArray<Counter>;
+  /**
+   * Render a document for whoever is running the program and write it to a stream.
+   *
+   * @remarks
+   * The context is {@link Render.context} for the stream, so the width, the colour, the links and the audience
+   * come from the services the program already has, and the text is written with `Console.log` or
+   * `Console.error`: a test captures it by swapping the `Console`. With `format: "auto"` the renderer follows
+   * the audience, and the width is unbounded for an agent and a CI.
+   *
+   * An agent is never written an escape of any kind, even with an explicit `format: "ansi"`: its context is
+   * colourless and its links are off. A document that renders to nothing prints nothing.
+   *
+   * `CurrentRuntimeEnv` is read if the environment has one and is not required: a `ci` audience prints
+   * GitHub's log format only when it says GitHub Actions, and plain text otherwise, including when it is
+   * absent. An explicit `format` is honoured whatever the audience.
+   *
+   * @param doc - the document
+   * @param options - the stream and the format
+   */
+  static readonly print: (doc: Document, options?: DocPrintOptions) => Effect.Effect<void, never, CliTheme | TerminalEnv | Audience | CliLinks>;
+}
+//#endregion
+//#region src/CliLinks.d.ts
+/**
+ * Whether file links open in an editor.
+ *
+ * @remarks
+ * `vscode` writes `vscode://file/<path>:<line>:<col>`, `file` writes `file://<path>`, `off` writes no file link, and
+ * `auto` picks `vscode` when it finds a signal of VS Code and `file` otherwise.
+ *
+ * @public
+ */
+type EditorLinks = "auto" | "vscode" | "file" | "off";
+/**
+ * The shape of the {@link CliLinks} service: the mode decided, and the URL a link target becomes.
+ *
+ * @public
+ */
+interface CliLinksShape {
+  /** The mode `auto` resolved to, or the one that was asked for. */
+  readonly mode: "vscode" | "file" | "off";
+  /**
+   * The URL a target opens, or `None` when it has none.
+   *
+   * @remarks
+   * A `{ url }` target is its URL, whatever the mode. A `{ file }` target is `vscode://file/<path>:<line>:<col>` or
+   * `file://<path>`, with the path URL-encoded; `off` gives it none, and so does a relative path when the layer
+   * has no working directory to resolve it against. A column needs a line.
+   */
+  readonly target: (target: LinkTarget) => Option.Option<string>;
+}
+/**
+ * Options for {@link CliLinks.layer}.
+ *
+ * @public
+ */
+interface CliLinksOptions {
+  /** The setting, `auto` by default. An environment variable the consumer names beats it. */
+  readonly editorLinks?: EditorLinks | undefined;
+  /** The environment variable that overrides the setting, read through `Config`. Not read unless named. */
+  readonly envVar?: string | undefined;
+  /** The working directory; `PWD` through `Config`, then `Path.resolve(".")`, when omitted. */
+  readonly cwd?: string | undefined;
+}
+/**
+ * The options of {@link CliLinks.linker}.
+ *
+ * @public
+ */
+interface CliLinksLinkerOptions {
+  /** The service that turns a target into a URL. */
+  readonly links: CliLinksShape;
+  /** Whether the stream's terminal renders OSC 8 hyperlinks. */
+  readonly hyperlinks: boolean;
+  /** Who the output is for. */
+  readonly audience: AudienceKind;
+}
+declare const CliLinks_base: Context.ServiceClass<CliLinks, "@effected/cli/CliLinks", CliLinksShape>;
+/**
+ * Editor-aware links for file targets: where a link to a file opens.
+ *
+ * @remarks
+ * The mode is decided once, when the layer is built. `auto` is `vscode` when `CurrentRuntimeEnv.terminal` is
+ * `vscode` (`TERM_PROGRAM=vscode`) or a `.vscode/` directory sits at the project root, and `file` otherwise. The
+ * root is the nearest directory, from the working directory up, that holds `.git` or `pnpm-workspace.yaml`; the
+ * climb is bounded, at most 64 directories above the working directory, and stops where `Path.dirname` reaches the
+ * filesystem root. With no root, the working directory itself is checked.
+ *
+ * Whether a link is written at all is a separate question, answered by {@link CliLinks.linker}.
+ *
+ * @public
+ */
+export declare class CliLinks extends CliLinks_base {
+  /**
+   * The links for the working directory, reading the filesystem for a `.vscode/` directory.
+   *
+   * @remarks
+   * A layer-returning function mints a fresh layer per call: call it once and bind the result to a constant.
+   *
+   * @param options - the setting, the environment variable that overrides it, and the working directory
+   */
+  static readonly layer: (options?: CliLinksOptions) => Layer.Layer<CliLinks, never, FileSystem.FileSystem | Path.Path | CurrentRuntimeEnv>;
+  /**
+   * Links fixed to a mode, with no filesystem: a relative path has no link, since there is no working directory.
+   *
+   * @param mode - `vscode`, `file` or `off`
+   */
+  static readonly layerTest: (mode: "vscode" | "file" | "off") => Layer.Layer<CliLinks>;
+  /**
+   * The function that writes a link: a target and a label in, the label out, wrapped in OSC 8 when it should be.
+   *
+   * @remarks
+   * It writes the hyperlink `ESC ] 8 ; ; URL ESC \ label ESC ] 8 ; ; ESC \` only when the stream's terminal can
+   * render it (`hyperlinks`) and the audience is not an agent, which never gets an escape of any kind; in every other
+   * case, and whenever the target has no URL, it returns the label unchanged. The URL has its control characters
+   * removed again here, so a hostile target cannot end the sequence early or start another, and a URL whose scheme is
+   * not one a link may have (`javascript:`, `data:`, and the like; the same list markdown uses) is the label alone. It is pure and cheap,
+   * which {@link RenderContext}'s `link` requires.
+   *
+   * @param options - the links, whether hyperlinks are available, and the audience
+   */
+  static readonly linker: (options: CliLinksLinkerOptions) => (target: LinkTarget, label: string) => string;
+}
+//#endregion
+//#region src/CliLogger.d.ts
+/**
+ * How a log record is turned into a line.
+ *
+ * @public
+ */
+interface CliLoggerOptions {
+  /**
+   * Render one message. Defaults to joining an array with spaces and
+   * `String`-ing anything else.
+   *
+   * @remarks
+   * An array arrives because `Effect.log("synced", 3, "repos")` is variadic.
+   *
+   * The text is sanitised, because it is whatever the program logged: with the default render, the line has its
+   * escape sequences and control characters removed (a line break stays one, a tab becomes a space); with yours, you
+   * receive the string parts already sanitised and own what you add, a colour included. Under GitHub Actions, where
+   * `CurrentRuntimeEnv` says so, a line the runner would read as a workflow command is neutralized either way.
+   *
+   * The logger reads `CurrentRuntimeEnv` from the logging fiber's context, so a line logged outside its scope
+   * (`CliLogger.layer()` provided alone, with no `CurrentRuntimeEnv`, or the warnings logged while `CliRuntime.main`
+   * builds its environment) is sanitised but not neutralized. Provide the environment around the program, as `main`
+   * does, for the neutralizing to apply.
+   */
+  readonly render?: ((message: unknown) => string) | undefined;
+  /**
+   * The level at and above which output goes to stderr. Defaults to `"All"`,
+   * so every log level is a diagnostic and stdout carries only what the
+   * program writes with `Console.log`.
+   *
+   * @remarks
+   * Pass `"Error"` to send only errors to stderr, for a tool whose output *is*
+   * its log lines rather than a separate document written with
+   * `Console.log`.
+   */
+  readonly stderrFrom?: LogLevel.LogLevel | undefined;
+}
+/**
+ * A `Logger` that renders CLI output rather than service logs: no timestamp, level or fiber id, with every level
+ * going to stderr by default so stdout carries only what the program writes.
+ *
+ * @remarks
+ * Effect's default logger emits `[00:33:56.619] INFO (#2): message`. That is
+ * the right shape for a long-running service being scraped and the wrong one
+ * for a tool a person is watching: the timestamp, level and fiber id are noise
+ * in front of output a human is reading, and they make a formatted block — a
+ * permissions table, a summary — unreadable.
+ *
+ * **A program that never installs a CLI logger looks correct in review and
+ * ships timestamps to its users**, so install this one at the program's
+ * boundary.
+ *
+ * It writes through the `Console` reference read off the logging fiber,
+ * synchronously, as core's own default logger does: `Logger.make` takes a
+ * synchronous callback, and a `Stdio` sink write is an `Effect` a logger cannot
+ * `yield*`. `Console.Console` is a `Context.Reference`, so it never appears in
+ * `R`, and a test swaps the reference rather than stubbing a global.
+ *
+ * @example
+ * ```ts
+ * import { CliLogger } from "@effected/cli"
+ * import { Console, Effect } from "effect"
+ *
+ * const program = Effect.gen(function* () {
+ *   yield* Effect.log("synced 3 repos")    // stderr, no timestamp — a diagnostic
+ *   yield* Console.log("3 repos synced")   // stdout — the program's actual output
+ *   yield* Effect.logError("one failed")   // stderr
+ * })
+ *
+ * program.pipe(Effect.provide(CliLogger.layer()))
+ * ```
+ *
+ * `stderrFrom` defaults to `"All"`: a CLI's stdout is its product, so every
+ * log level is a diagnostic unless a consumer narrows the threshold. Write
+ * program output with `Console.log`, never `Effect.log`. Pass
+ * `stderrFrom: "Error"` for a tool whose output *is* its log lines.
+ *
+ * @public
+ */
+export declare class CliLogger {
+  private constructor();
+  /**
+   * The logger itself, for composing into an existing `Logger.layer` set.
+   *
+   * @remarks
+   * Prefer {@link CliLogger.layer}. Reach for this only when you are building
+   * the logger set yourself and want this one among several.
+   */
+  static readonly make: (options?: CliLoggerOptions) => Logger.Logger<unknown, void>;
+  /**
+   * Replace the default logger with this one.
+   *
+   * @remarks
+   * `Logger.layer` **replaces** rather than merges, so nothing is emitted twice.
+   *
+   * Merge this into the layer you provide to the whole program rather than
+   * providing it beneath: merged, it also covers lines emitted during layer
+   * construction, which is exactly where a startup failure prints.
+   */
+  static readonly layer: (options?: CliLoggerOptions) => Layer.Layer<never>;
+}
+//#endregion
+//#region src/CliLog.d.ts
+/**
+ * Options for `CliLog.layer`.
+ *
+ * @public
+ */
+interface CliLogOptions {
+  /**
+   * The diagnostics level, for a host that has already decided it.
+   *
+   * @remarks
+   * Beats `envVar`, which is then not read at all (so a bad value there neither warns nor overrides this), and
+   * loses to core's `--log-level` flag like every diagnostics level: the sink follows the flag while it is set.
+   */
+  readonly level?: LogLevel.LogLevel | undefined;
+  /**
+   * The environment variable that sets the diagnostics level, for example `MYTOOL_LOG_LEVEL`. Read through
+   * `Config`, never `process`. Unset or empty means `None`. Ignored when `level` is given.
+   */
+  readonly envVar?: string | undefined;
+  /**
+   * Whether to install the plain `CliLogger` for ordinary lines. `true` by default.
+   *
+   * @remarks
+   * `false` is the diagnostics-only mode for a library host (an MCP server, a test reporter): the layer installs
+   * only the diagnostics sink, the file sink if any, and `extraLoggers`. With no level set as well, stderr gets
+   * no output. An invalid level in `envVar` still prints its one warning line, through a private `CliLogger`,
+   * since that is a configuration error the host should see.
+   *
+   * Only `CliLog`'s own records are silenced. Under `CliRuntime.main`, what the platform logs while it builds follows
+   * the build-time format: in NDJSON (`json`, or `auto` for an agent or a CI) it goes through this layer, so `false`
+   * silences it there as at runtime; otherwise it goes through a plain `CliLogger`, routed by `logger.stderrFrom` as the
+   * host set it. The audience-override warning is a
+   * configuration error and is never silenced: it is written exactly once, as NDJSON when the build-time format is
+   * NDJSON and as a plain line otherwise, whatever this option says, to stderr alone (never stdout, whatever
+   * `logger.stderrFrom` says) and never to `extraLoggers` or the file sink. The failure report and the `CliMessage` lines
+   * always go through a plain `CliLogger`.
+   */
+  readonly plainLogger?: boolean | undefined;
+  /**
+   * `json` is NDJSON, `pretty` a human line, `auto` (the default) decides by the audience alone: NDJSON for an agent
+   * or a CI, the pretty `CliLogger` line for a human, at build time and at runtime alike.
+   *
+   * @remarks
+   * Stderr's terminal state is never consulted, so a human piping stderr to a file gets plain lines, never a mix of
+   * plain and NDJSON; colour still follows `stderr.color`, so those lines carry no escapes when stderr is not a colour
+   * terminal. Pass `format: "json"` for machine-readable logs whoever runs the program.
+   *
+   * Under `CliRuntime.main` with `env.log`, what the platform logs while it builds is written before the platform
+   * provides the terminal or the arguments, so `auto` decides those lines from what needs no platform: an audience
+   * flag in {@link CliLogOptions.argv}, else the audience override variable (`env.audienceEnvVar`), else agent and
+   * CI detection from the environment. An agent or a CI gets NDJSON, as its runtime lines are; anything else gets
+   * a plain line, the same choice the runtime lines make. `json` is NDJSON and `pretty` plain throughout.
+   */
+  readonly format?: "auto" | "json" | "pretty" | undefined;
+  /**
+   * The program's arguments, for the format of what the platform logs while it builds under `CliRuntime.main` with
+   * `format: "auto"`: an audience flag (`--agent`, `--ci`, `--human`, `--audience <kind>`) in them decides those
+   * lines as it decides the run's. Only `CliRuntime.main` reads this.
+   *
+   * @remarks
+   * The arguments core parses come from the platform's `Stdio`, which does not exist until the platform is built, and
+   * this package never reads `process`. A Node host passes `process.argv.slice(2)`; without it the build-time lines
+   * follow the environment alone, so `--agent` with no agent detected gets plain lines until the platform is built.
+   */
+  readonly argv?: ReadonlyArray<string> | undefined;
+  /** Options for the `CliLogger` this layer builds for ordinary log lines; see {@link CliLoggerOptions}. */
+  readonly logger?: CliLoggerOptions | undefined;
+  /**
+   * Loggers to keep beside the `CliLogger` and the sink, for example a telemetry logger: the layer owns the
+   * whole set, so anything not listed here is dropped.
+   *
+   * @remarks
+   * Each is floored at the `MinimumLogLevel` it had, like the `CliLogger`, so lowering the level for the
+   * diagnostics sink never makes it see records it would not have seen otherwise.
+   */
+  readonly extraLoggers?: ReadonlyArray<Logger.Logger<unknown, unknown>> | undefined;
+  /**
+   * Whether a line the GitHub Actions runner would read as a workflow command is neutralized. `auto`, the default,
+   * follows the `CurrentRuntimeEnv` of the fiber that logs, and where that fiber has none, `runtimeEnv`, else the one
+   * the layer was built with: a host that builds this layer over its environment covers records logged outside it
+   * too. `true` always neutralizes, `false` never does.
+   */
+  readonly neutralize?: boolean | "auto" | undefined;
+  /**
+   * The runtime environment `neutralize: "auto"` falls back to for a record whose fiber has no `CurrentRuntimeEnv`.
+   *
+   * @remarks
+   * Given, it is used in place of the `CurrentRuntimeEnv` the layer captured when it was built, and beats it; the
+   * logging fiber's own `CurrentRuntimeEnv` still comes first. The capture is invisible in the layer's type (it is read
+   * if present, never required), so a host that builds this layer outside its environment either passes the snapshot
+   * here, for example `RuntimeEnv.fromRecord(process.env)`, or provides `CurrentRuntimeEnv` around the layer.
+   *
+   * Neutralization under `"auto"` reads the logging fiber's `CurrentRuntimeEnv`, then this option, then the
+   * `CurrentRuntimeEnv` captured when the layer was built. With none of the three, a record is not neutralized: set
+   * this option, provide `CurrentRuntimeEnv` around the layer, or pass `neutralize: true`. Every `CliLog.layer`
+   * overload points here.
+   */
+  readonly runtimeEnv?: RuntimeEnv | undefined;
+}
+/**
+ * Where the file sink writes: a literal path, or the environment variable that holds it.
+ *
+ * @public
+ */
+type CliLogFile = {
+  readonly envVar: string;
+} | {
+  readonly path: string;
+};
+/**
+ * {@link CliLogOptions} with a file sink, which is what makes the layer require `FileSystem` and `Path`.
+ *
+ * @public
+ */
+interface CliLogFileOptions extends CliLogOptions {
+  /**
+   * Also write every record the sink accepts to a file as NDJSON, asynchronously.
+   *
+   * @remarks
+   * The line is identical to the stderr NDJSON line for the same log call and is filtered by the same
+   * {@link CliLog.Level}. Lines are queued and appended by a fiber scoped to the layer, so logging never waits
+   * on the disk, and the parent directory is created. The first write error prints exactly one stderr line,
+   * `diagnostics log file <path> failed: <message>; further file logging disabled`, and the program keeps
+   * running with its normal exit code: from then on lines, including any still queued, are discarded silently.
+   * Closing the layer's scope flushes the lines queued before it, unless the sink had already disabled itself.
+   * `{ envVar }` names the variable that holds the path; unset or empty, no file is written.
+   *
+   * `undefined` writes no file but keeps the requirements of a file sink (`FileSystem` and `Path`) in `R`, so a
+   * host whose sink is optional has one stable layer type either way.
+   *
+   * Under `CliRuntime.main` with `env.log`, what the platform logs while it builds, before it provides
+   * `FileSystem`, reaches stderr but not the file; the file starts with the program's own records.
+   */
+  readonly file: CliLogFile | undefined;
+}
+/**
+ * Diagnostics kept apart from a program's output: a level, a format and a place to write.
  *
  * @remarks
- * Follows the no-color.org rule: colour is off when stdout is not a
- * terminal, or when `NO_COLOR` is set to any **non-empty** value — an empty
- * `NO_COLOR=""` does not disable colour. `FORCE_COLOR` is ignored, matching
- * core's own formatter. The environment is read through the ambient
- * `ConfigProvider`, never `process`, so a test swaps it with
- * `Effect.provideService(ConfigProvider.ConfigProvider, ...)`. The kit's
- * default providers (`fromEnv`, `fromUnknown`) already treat an empty
- * `NO_COLOR` as unset, so the explicit `set === ""` check exists for a
- * provider constructed with `{ preserveEmptyStrings: true }`.
+ * Two kinds of line must never be silenced by a diagnostics default: the failure report
+ * `CliRuntime.reportFailures` writes through `CliLogger`, and the `CliMessage` lines. This package therefore
+ * never makes the diagnostics level a global switch. The diagnostics logger filters on its **own** threshold,
+ * {@link CliLog.Level}, and writes to stderr only.
+ *
+ * `CliLog.layer` **owns the whole logger set**. It builds a `CliLogger` for ordinary log lines and the
+ * diagnostics sink itself and replaces whatever was installed, without reading it, so there is no order to get
+ * wrong. Use it instead of `CliLogger.layer`, not with it: `CliLogger.layer` alone is the no-diagnostics path,
+ * and a `CliLogger.layer` layered on top would replace this layer's set.
+ *
+ * Effect drops a record below `MinimumLogLevel` before any logger runs, so to let a debug record reach the
+ * diagnostics logger `MinimumLogLevel` has to be lowered. `CliLog.layer` does that only when the
+ * diagnostics level is below the ambient minimum, and in the same step floors the `CliLogger` it built at the
+ * minimum it had, so it never prints a record the diagnostics level alone let through. A failure report is
+ * written outside the scope core's `--log-level` flag sets, so `--log-level none` does not silence it either.
+ *
+ * `format: "auto"`, the default, decides by the audience alone, at build time and at runtime alike: NDJSON for an
+ * agent or a CI, the pretty line for a human, whatever stderr's terminal state. A human piping stderr therefore gets
+ * plain lines (without escapes unless stderr is a colour terminal); pass `format: "json"` for machine-readable logs.
+ *
+ * The text a program logs is sanitised before anything is painted in the pretty line (the message, the component and an
+ * error's cause lose their escape sequences and control characters), and under GitHub Actions, where
+ * `CurrentRuntimeEnv` in the logging fiber's context says so, a line the runner would read as a workflow command is
+ * neutralized. An NDJSON record is not safe merely because `JSON.stringify` escapes control characters: the runner's
+ * legacy parser reads `##[` anywhere in a line, so under Actions it is written as the JSON escape `#\u0023[`, which
+ * decodes to the identical text. The file sink's lines are not read by the runner and are written as they are.
+ *
+ * `CurrentRuntimeEnv` is read from the logging fiber's context, and where that has none, from the `runtimeEnv` option,
+ * else from the layer's own build context (captured if present, never required), so a host that builds the layer over
+ * its environment, or names it with `runtimeEnv`, neutralizes every record. A record with none of the three (a program
+ * with no `CurrentRuntimeEnv` anywhere) is sanitised but not neutralized, unless the `neutralize` option says otherwise.
+ *
+ * Core's `--log-level` flag sets `MinimumLogLevel` inside the command. While it is set to something other than
+ * the value this layer installed, the diagnostics logger follows the flag instead of its own level: it writes
+ * every record that reaches it. The `CliLogger` prints the same record too, so a record at or above the ambient
+ * minimum is written twice, once plain and once to the diagnostics sink. Stderr is therefore not pure NDJSON while
+ * diagnostics are on: a parser reads the lines that start with `{`.
+ *
+ * One edge: a `--log-level` value that EQUALS the level this layer installed cannot be told from no flag, so the
+ * sink keeps filtering on its own level rather than following the flag. The plain `CliLogger` prints those records
+ * regardless.
+ *
+ * @example
+ * ```ts
+ * import { CliRuntime } from "@effected/cli"
+ * import { NodeRuntime, NodeServices } from "@effect/platform-node"
+ *
+ * // `env.log` makes `main` install `CliLog.layer`: set MYTOOL_LOG_LEVEL=debug to get diagnostics on stderr.
+ * NodeRuntime.runMain(
+ *   CliRuntime.main(program, {
+ *     platform: NodeServices.layer,
+ *     env: { audienceEnvVar: "MYTOOL_AUDIENCE", log: { envVar: "MYTOOL_LOG_LEVEL" } },
+ *   }),
+ * )
+ * ```
  *
  * @public
  */
-export declare class CliColor {
+export declare class CliLog {
   private constructor();
   /**
-   * The decision, for passing to a pure renderer as a plain boolean.
+   * The diagnostics threshold. Defaults to `None`, silent.
    *
-   * @public
+   * @remarks
+   * `CliLog.layer` sets it from the environment variable. A scope may raise it to narrow the output; it
+   * cannot lower it below the level the layer installed, because Effect has already dropped those records.
    */
-  static readonly enabled: Effect.Effect<boolean, never, Stdio.Stdio>;
+  static readonly Level: Context.Reference<LogLevel.LogLevel>;
   /**
-   * Core's default `CliOutput.Formatter`, coloured by the same decision as
-   * {@link CliColor.enabled}, so help text, parse errors and rendered
-   * output never disagree on whether colour is on.
+   * The whole logger set of a program: a `CliLogger` for ordinary lines plus the diagnostics sink.
    *
    * @remarks
-   * `overrides` replaces individual methods of the default formatter — for
-   * example `formatVersion`, to append a "via `<carrier>`" line without
-   * losing the other defaults. Each call mints a fresh layer; bind the
-   * result to a `const` or the decision is re-read every time it is
-   * provided.
+   * Replaces the installed loggers without reading them. Provide it on the program you pass to
+   * `CliRuntime.main`, or use `main`'s `env.log` option; never wrap it around `main`, whose own logger would
+   * replace this one. Bind it to a constant.
    *
-   * The `never` in its output does not mean it installs nothing.
-   * `CliOutput.Formatter` is a `Context.Reference`, whose key type is
-   * `never`, so this layer sets the formatter reference rather than
-   * providing a service. Every command it is provided to renders with the
-   * formatter it sets, and without it they fall back to core's default
-   * formatter.
+   * The requirements follow the format. `format: "json"` reads neither the audience nor the terminal, so it
+   * requires neither; `"pretty"` requires `TerminalEnv` alone, for the stderr colour; `"auto"` and an omitted
+   * format require both. A long-lived host that never builds a platform `Terminal` can provide
+   * `TerminalEnv.layerStdio()` for the pretty case.
    *
-   * @public
+   * A platform or program that installs its own `Logger.layer([...])` replaces this set: do not. The diagnostics
+   * then go silent with no error.
+   *
+   * The NDJSON line is core's `Logger.formatJson`, unchanged so it stays interoperable with Effect tooling: the
+   * `message` field is a string for one log argument and an array for several.
+   *
+   * Level parsing is case-insensitive and accepts `warn`, `warning`, `error`, `info`, `debug`, `trace`,
+   * `fatal`, `all` and `none`. An invalid value warns once, through the `CliLogger`, and leaves diagnostics
+   * off.
+   *
+   * With a `file` option ({@link CliLogFileOptions}) the layer also writes an async NDJSON file, and only then
+   * does it require `FileSystem` and `Path`, and it leaves them in `R` unprovided: the platform supplies them, or
+   * a test supplies a memory filesystem, so a host never provides Node inside its own layer.
+   *
+   * Without a `CurrentRuntimeEnv` around the layer, `"auto"` does not neutralize: see {@link CliLogOptions.runtimeEnv}.
+   *
+   * @param options - the level, the env var, the format, the `CliLogger` options and the optional file sink
    */
-  static readonly formatterLayer: (overrides?: Partial<CliOutput.Formatter>) => Layer.Layer<never, never, Stdio.Stdio>;
+  static layer(options: CliLogOptions & {
+    readonly format: "json";
+    readonly file?: undefined;
+  }): Layer.Layer<never, never, never>;
+  /**
+   * The logger set with NDJSON diagnostics and a file sink; see the first overload.
+   *
+   * @remarks
+   * Without a `CurrentRuntimeEnv` around the layer, `"auto"` does not neutralize: see {@link CliLogOptions.runtimeEnv}.
+   *
+   * @param options - the level, the env var, the `CliLogger` options and the file sink
+   */
+  static layer(options: CliLogFileOptions & {
+    readonly format: "json";
+  }): Layer.Layer<never, never, FileSystem.FileSystem | Path.Path>;
+  /**
+   * The logger set with pretty diagnostics; see the first overload.
+   *
+   * @remarks
+   * Without a `CurrentRuntimeEnv` around the layer, `"auto"` does not neutralize: see {@link CliLogOptions.runtimeEnv}.
+   *
+   * @param options - the level, the env var and the `CliLogger` options
+   */
+  static layer(options: CliLogOptions & {
+    readonly format: "pretty";
+    readonly file?: undefined;
+  }): Layer.Layer<never, never, TerminalEnv>;
+  /**
+   * The logger set with pretty diagnostics and a file sink; see the first overload.
+   *
+   * @remarks
+   * Without a `CurrentRuntimeEnv` around the layer, `"auto"` does not neutralize: see {@link CliLogOptions.runtimeEnv}.
+   *
+   * @param options - the level, the env var, the `CliLogger` options and the file sink
+   */
+  static layer(options: CliLogFileOptions & {
+    readonly format: "pretty";
+  }): Layer.Layer<never, never, TerminalEnv | FileSystem.FileSystem | Path.Path>;
+  /**
+   * The logger set with the format decided by the audience; see the first overload.
+   *
+   * @remarks
+   * Without a `CurrentRuntimeEnv` around the layer, `"auto"` does not neutralize: see {@link CliLogOptions.runtimeEnv}.
+   *
+   * @param options - the level, the env var, the format and the `CliLogger` options
+   */
+  static layer(options?: CliLogOptions & {
+    readonly file?: undefined;
+  }): Layer.Layer<never, never, Audience | TerminalEnv>;
+  /**
+   * The logger set with the format decided by the audience, and a file sink; see the first overload.
+   *
+   * @remarks
+   * Without a `CurrentRuntimeEnv` around the layer, `"auto"` does not neutralize: see {@link CliLogOptions.runtimeEnv}.
+   *
+   * @param options - the level, the env var, the format, the `CliLogger` options and the file sink
+   */
+  static layer(options: CliLogFileOptions): Layer.Layer<never, never, Audience | TerminalEnv | FileSystem.FileSystem | Path.Path>;
+  /**
+   * Mark the log records an effect emits as coming from `name`.
+   *
+   * @remarks
+   * Shown as `[name]` in pretty output and as `annotations.component` in NDJSON.
+   *
+   * @param name - the component
+   */
+  static readonly component: (name: string) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+}
+//#endregion
+//#region src/CliEnv.d.ts
+/**
+ * Options for {@link CliEnv.layer} and for `CliRuntime.main`'s `env` option.
+ *
+ * @public
+ */
+interface CliEnvOptions {
+  /** The environment variable that overrides the audience, read through `Config`; see `Audience.layer`. */
+  readonly audienceEnvVar?: string | undefined;
+  /**
+   * Overrides the stderr terminal check; `Stdio` reports only stdout, so stderr mirrors it otherwise.
+   *
+   * @remarks
+   * Mirroring means a program whose stdout is a terminal but whose stderr is redirected to a file still paints
+   * stderr (a failure report, a warning) with colour escapes. A Node host that redirects stderr passes the real
+   * answer: `env: { stderrIsTerminal: Effect.sync(() => process.stderr.isTTY === true) }`. Core's `Stdio` has no
+   * stderr terminal check to read instead; that gap is tracked upstream as Effect-TS/effect#8639.
+   */
+  readonly stderrIsTerminal?: Effect.Effect<boolean> | undefined;
+  /** Options for the theme; see {@link CliThemeOptions}. */
+  readonly theme?: CliThemeOptions | undefined;
+  /**
+   * Diagnostics options. Only `CliRuntime.main` reads this: when given, `main` uses `CliLog.layer` with these
+   * options as the program's logger, instead of the default `CliLogger.layer()`. The platform is built under
+   * that logger, so a line it logs while building goes to stderr.
+   *
+   * @remarks
+   * It may carry the `file` option, which also writes an async NDJSON file. The platform must then provide
+   * `FileSystem` and `Path`, and `main`'s type says so when it does not.
+   *
+   * A platform or program that installs its own `Logger.layer([...])` replaces this logger set, and the
+   * diagnostics go silent with no error: do not install one. See `CliLog.layer`. Only `CliLog`'s own records can be
+   * silenced (`plainLogger: false`): what the platform logs while it builds goes through the full `CliLog` when its
+   * build-time format is NDJSON (`json`, or `auto` for an agent or a CI; see `CliLogOptions.format`) and through a plain
+   * `CliLogger` otherwise, routed by `logger.stderrFrom` as the host set it. The audience-override warning is never silenced: it is written exactly once, in NDJSON when
+   * the build-time format is NDJSON and as a plain line otherwise, to stderr alone (never stdout, whatever
+   * `logger.stderrFrom` says) and never to the host's `extraLoggers` or log file. The failure report and the `CliMessage` lines always
+   * go through a plain `CliLogger`.
+   */
+  readonly log?: CliLogOptions | CliLogFileOptions | undefined;
+  /**
+   * Methods of core's `CliOutput.Formatter` to replace in the one `CliRuntime.main` installs, for example
+   * `formatVersion` to name the carrier a bin runs through. Only `CliRuntime.main` reads this.
+   *
+   * @remarks
+   * `main` installs a coloured default formatter inside the platform, which shadows any formatter the platform
+   * sets; this is the way to keep a method of your own. Methods you omit keep the coloured defaults.
+   */
+  readonly formatter?: Partial<CliOutput.Formatter> | undefined;
+  /**
+   * Turns an absolute path into its display form, for example relative to the workspace: the stack frames of the
+   * default failure report are shown through it. Only `CliRuntime.main` reads this. The identity by default.
+   */
+  readonly displayPath?: ((absolute: string) => string) | undefined;
+  /**
+   * Which frames of a defect's stack the default failure report shows: `app`, the default, leaves out every
+   * `node_modules` frame (Effect's and any other dependency's) and the runtime's own (every `node:` frame and every
+   * frame with no file), and prints how many it left out after the frames it shows, as
+   * `(+N internal frames hidden)`, or `no user frames (N internal frames hidden)` when none is left; `all` shows
+   * every frame. Applies to the report `main` writes, `FailureDetails.defaultLines` and `FailureDetails.lines`. Only
+   * `CliRuntime.main` reads this.
+   */
+  readonly stackFrames?: "app" | "all" | undefined;
+  /** Whether file links open in an editor; `auto` by default. See {@link CliLinks}. */
+  readonly editorLinks?: EditorLinks | undefined;
+  /** The environment variable that overrides `editorLinks`, read through `Config`. Not read unless named. */
+  readonly editorLinksEnvVar?: string | undefined;
+}
+/**
+ * The services {@link CliEnv.layer} provides.
+ *
+ * @public
+ */
+type CliEnvServices = CurrentRuntimeEnv | TerminalEnv | Audience | CliTheme | CliLinks | Terminal.Terminal;
+/**
+ * Options for {@link CliEnv.layerTest}: the answers a test fixes. Every field has a quiet default.
+ *
+ * @public
+ */
+interface CliEnvTestOptions {
+  /** Whether standard input, output and error are all terminals; `false` by default, as for a pipe. */
+  readonly tty?: boolean | undefined;
+  /**
+   * The `TERM` the layer's own builds read: `dumb` makes a terminal not interactive and, with the theme's glyphs at
+   * `auto`, draws ASCII. Unset by default, whatever the host's `TERM` is.
+   */
+  readonly term?: string | undefined;
+  /** The audience; `human` by default. */
+  readonly audience?: AudienceKind | undefined;
+  /** The width of the terminal, in columns; none by default, so a width falls back to the reader's (80). */
+  readonly columns?: number | undefined;
+  /** The colour level of both stdout and stderr; `none` by default. Fixed as given: `term` does not change it. */
+  readonly color?: ColorLevel | undefined;
+  /** Options for the theme, as {@link CliEnvOptions.theme}; its glyphs are `auto` by default, so `term` decides. */
+  readonly theme?: CliThemeOptions | undefined;
+}
+/**
+ * The services {@link CliEnv.layerTest} provides.
+ *
+ * @public
+ */
+type CliEnvTestServices = TerminalEnv | Audience | CliTheme;
+/**
+ * The environment services a CLI reads, built once and in the right order.
+ *
+ * @remarks
+ * Builds `CurrentRuntimeEnv`, `TerminalEnv`, `Audience`, `CliTheme` and `CliLinks`, and sets `CliInteractive` from them, then
+ * installs the two gates for the program: `CliPrompt.gateTerminal`, which replaces `Terminal` with a quiet one when
+ * the run is not interactive so no prompt runner ever attaches to stdin, and `CliPrompt.gateWizard`, which drops
+ * `--wizard` then. `TerminalEnv` is built from the real terminal first. The layer therefore also outputs
+ * `Terminal`, the gated one, and consumers never compose the gates themselves. A
+ * `Context.Reference`'s key type is `never`, so the layer's output type does not list `CliInteractive`: it sets
+ * the reference rather than providing a service. Every read of the environment goes through `Config` and
+ * degrades to "unset" when it fails, so building the layer does not fail on a bad provider; it fails only when
+ * `Stdio` or `Terminal` do.
+ *
+ * `CliLinks` reads `FileSystem` and `Path` from the surrounding context if it has them, and does not require them: a
+ * `.vscode/` directory is looked for, and a relative path resolved, only when the platform is provided OUTSIDE this
+ * layer, as `CliRuntime.main` does. Without them `auto` is `vscode` on the terminal signal alone.
+ *
+ * Not interactive, the gated `Terminal`'s `readLine` fails as a quit, its input is already ended and its `display`
+ * writes nothing. A program that reads piped data must read `Stdio.stdin`, and one that writes output must use
+ * `Console` or `Stdio`, never `Terminal`. It also installs `CliTheme.promptTheme`, so core's prompts follow the
+ * theme.
+ *
+ * @public
+ */
+export declare class CliEnv {
+  private constructor();
+  /**
+   * The environment services for the terminal `Stdio` and `Terminal` describe.
+   *
+   * @remarks
+   * A layer-returning function mints a fresh layer per call: call it once and bind the result to a constant.
+   *
+   * @param options - the audience env var, the stderr check and the theme options
+   */
+  static readonly layer: (options?: CliEnvOptions) => Layer.Layer<CliEnvServices, never, Stdio.Stdio | Terminal.Terminal>;
+  /**
+   * The environment services a test fixes, needing nothing and reading nothing of the host's: `TerminalEnv` and
+   * `Audience` from the answers given, `CliTheme` built from them as {@link CliEnv.layer} builds it, and
+   * `CliInteractive` set from them by the same rule (a human, every stream a terminal, and a `TERM` that is not
+   * `dumb`).
+   *
+   * @remarks
+   * `term` is handed to the theme and interactivity builds alone, through a `ConfigProvider` of their own: the
+   * program under the layer keeps its own provider, and a host's `TERM` (a test runner in a dumb terminal) never
+   * decides. A screen or a live view also needs `UiStreams` from `@effected/cli/ui`, which `CliUiTest` provides; this
+   * layer provides no `Terminal` and installs neither of `CliEnv.layer`'s prompt gates.
+   *
+   * A layer-returning function mints a fresh layer per call: call it once and bind the result to a constant.
+   *
+   * @param options - whether the streams are terminals, the `TERM`, the audience, the width, the colour and the theme
+   */
+  static readonly layerTest: (options?: CliEnvTestOptions) => Layer.Layer<CliEnvTestServices>;
 }
 //#endregion
 //#region src/CliExit.d.ts
@@ -71,7 +2049,7 @@ declare const CliExit_base: Context.ServiceClass<CliExit, "@effected/cli/CliExit
  * handler must return normally — yet the process must exit non-zero. Writing
  * `process.exitCode` works only because Node's `runMain` skips
  * `process.exit(0)` on success; `process.exit(n)` in a handler skips every
- * finalizer. {@link CliRuntime.main} reads this cell after the program
+ * finalizer. `CliRuntime.main` reads this cell after the program
  * succeeds and turns a non-zero code into a marked failure the runtime's
  * teardown honours, on any runtime, with finalizers intact.
  *
@@ -117,109 +2095,301 @@ export declare class CliExit extends CliExit_base {
   static readonly set: (code: number) => Effect.Effect<void, never, CliExit>;
 }
 //#endregion
-//#region src/CliLogger.d.ts
+//#region src/CliFailure.d.ts
 /**
- * How a log record is turned into a line.
+ * The protocol an error class implements to say how a failure is shown: a method under this key that returns the
+ * document.
+ *
+ * @remarks
+ * `CliFailure.toDoc` calls it for a typed failure that has one, so an application error draws itself (a heading, a
+ * table of what went wrong) and the default report uses it with no registration. A `Symbol.for` key, so two copies
+ * of this package agree on it.
  *
  * @public
  */
-interface CliLoggerOptions {
+export declare const CliDoc: unique symbol;
+/**
+ * An error that draws itself: see {@link CliDoc}.
+ *
+ * @public
+ */
+interface CliDocSource {
+  readonly [CliDoc]: () => Document;
+}
+/**
+ * Options for {@link CliFailure.toDoc}.
+ *
+ * @public
+ */
+interface CliFailureOptions {
   /**
-   * Render one message. Defaults to joining an array with spaces and
-   * `String`-ing anything else.
-   *
-   * @remarks
-   * An array arrives because `Effect.log("synced", 3, "repos")` is variadic.
+   * A document per error `_tag`, for errors that do not implement {@link CliDoc}. A tag with no entry is shown by
+   * the default rules.
    */
-  readonly render?: ((message: unknown) => string) | undefined;
+  readonly render?: Readonly<Record<string, (error: unknown) => Document>> | undefined;
+  /** Turns an absolute path into its display form, for the stack frames; the identity by default. */
+  readonly displayPath?: ((absolute: string) => string) | undefined;
   /**
-   * The level at and above which output goes to stderr. Defaults to `"All"`,
-   * so every log level is a diagnostic and stdout carries only what the
-   * program writes with `Console.log`.
-   *
-   * @remarks
-   * Pass `"Error"` to restore the old split, for a tool whose output *is*
-   * its log lines rather than a separate document written with
-   * `Console.log`.
+   * Which frames of a defect's stack are shown. `app`, the default, shows the program's own: every `node_modules`
+   * frame (Effect's and any other dependency's), `node:internal` and the runtime's generator frames are left out and
+   * counted. When that leaves no frame, as for a program run from its install under `node_modules` (a global
+   * install, `npx`, a pnpm store), only the runtime's and Effect's are left out, so its own frames still show. `all`
+   * shows every frame, unfiltered.
    */
-  readonly stderrFrom?: LogLevel.LogLevel | undefined;
+  readonly stackFrames?: "app" | "all" | undefined;
 }
 /**
- * A `Logger` that renders CLI output rather than service logs.
+ * A failure as a document: what the default report prints, and a building block for a custom one.
  *
  * @remarks
- * Effect's default logger emits `[00:33:56.619] INFO (#2): message`. That is
- * the right shape for a long-running service being scraped and the wrong one
- * for a tool a person is watching: the timestamp, level and fiber id are noise
- * in front of output a human is reading, and they make a formatted block — a
- * permissions table, a summary — unreadable.
+ * One run of blocks per `Cause` reason. A typed failure is, in order of preference: the document of an error that
+ * implements {@link CliDoc}; the document `options.render` holds for its `_tag`; for `Cancelled` and
+ * `NotInteractive`, their one fixed line; a `Tree` of the rejected values, for a schema error or issue; else a failure
+ * status line with its message. A defect is its message followed by a collapsible `stack` of the program's own frames,
+ * each a file link (so a terminal can open it in an editor) shown through `displayPath`, with the runtime's frames (every
+ * `node:` frame and every frame with no file) and every `node_modules` frame (Effect's and any other dependency's)
+ * left out unless `stackFrames` is `all`. A frame is classified by its file alone, never by its function name, so a
+ * program's own thunk that V8 names by Effect's method alias is still shown. When that would
+ * leave no frame at all, as for a program run from its own install under `node_modules`, only the runtime's and
+ * Effect's are left out. Then an
+ * `Error.cause` chain as a tree. When cleaning leaves no frame the stack says
+ * `no user frames (N internal frames hidden)`, never an empty block; when frames survive and some were left out, the
+ * count follows them as `(+N internal frames hidden)`. A reason that ran under spans is followed by
+ * `in: outer › inner`. Interrupts are not rendered beside a real failure, and a cause with only interrupts is the
+ * one line `interrupted`.
+ *
+ * All text goes through the document, so a control character in a message or a stack frame never reaches the terminal.
+ * Render it with `Render.context` and `Render.plain`, `ansi`, `markdown` or `githubLog`, or `Doc.print` it.
  *
- * **This is not a preference, and it is not visible from the call site.** A
- * program that never installs a CLI logger looks correct in review and ships
- * timestamps to its users; the consumer this package was extracted from had it
- * missing for a day while its own docs claimed it existed.
+ * @public
+ */
+export declare class CliFailure {
+  private constructor();
+  /**
+   * Build the document of a cause.
+   *
+   * @param cause - the failure
+   * @param options - per-tag documents and a path display function
+   */
+  static readonly toDoc: (cause: Cause.Cause<unknown>, options?: CliFailureOptions) => Document;
+}
+//#endregion
+//#region src/CliInteractive.d.ts
+declare const CliInteractive_base: Context.Reference<boolean>;
+/**
+ * Whether this run may prompt a person: a human audience, with a terminal on
+ * both standard input and standard output, and a `TERM` that is not `dumb`.
  *
- * ## Why the `Console` reference, and not `Stdio`
+ * @remarks
+ * A `Context.Reference`, not a `Context.Service`, for three reasons. It is one
+ * boolean with a safe default, which is what a reference is for. A scoped
+ * override, {@link CliInteractive.unless}, is a plain
+ * `Effect.provideService`, so a command can switch prompting off for one
+ * subtree without a layer. And forgetting to provide it is not a type error
+ * but a harmless answer, since it reads `false` when no layer is provided: a
+ * program that never wired it refuses to prompt rather than hanging on a
+ * terminal that is not there. Read it with `yield* CliInteractive`.
  *
- * The obvious design — write through `Stdio`'s `stdout()` / `stderr()` sinks —
- * does not fit. `Logger.make` takes a **synchronous** callback and a `Sink`
- * write is an `Effect`: a logger cannot `yield*`.
+ * Because a reference's key type is `never`, {@link CliInteractive.layer} and
+ * {@link CliInteractive.layerTest} are typed `Layer<never>`: they set the
+ * reference rather than provide a service.
  *
- * Writing to `process.stdout` would fit, and is what the consumer did first,
- * but it drags a platform assumption into a library and — the part that
- * actually matters — makes the stream split **untestable**, because asserting
- * it means monkey-patching a global inside a runner that is itself writing to
- * those streams.
+ * @public
+ */
+export declare class CliInteractive extends CliInteractive_base {
+  /**
+   * Decide from the audience and the terminal: `true` only for a human audience with a terminal on both
+   * standard input and standard output, and a `TERM` that is not `dumb`.
+   *
+   * @remarks
+   * A dumb terminal is a terminal, but it cannot move the cursor or take synchronized output, which a prompt or a
+   * screen redrawing in place needs: it gets what a pipe gets. `TERM` is read through the ambient `ConfigProvider`,
+   * as `@effected/env` reads the environment, so it adds no requirement; a test fixes it with
+   * `Effect.provideService(ConfigProvider.ConfigProvider, ConfigProvider.fromUnknown({ TERM: "dumb" }))`.
+   *
+   * Bind the layer to a constant and provide it once; `Audience` and `TerminalEnv` come from `@effected/env`.
+   */
+  static readonly layer: Layer.Layer<never, never, Audience | TerminalEnv>;
+  /**
+   * A fixed answer that needs nothing.
+   *
+   * @param value - whether the run is interactive
+   */
+  static readonly layerTest: (value: boolean) => Layer.Layer<never>;
+  /**
+   * Run `self` with interactivity switched off when `condition` holds.
+   *
+   * @remarks
+   * It only narrows: `unless(false)` leaves the current value alone and never turns interactivity on, so a
+   * non-interactive scope stays non-interactive. The outer value is restored when `self` ends, whether it
+   * succeeds, fails or is interrupted.
+   *
+   * A flag that resolves the audience (`--human`, under `CliAudience.runWith` or `provide`) recomputes interactivity
+   * from the terminal facts, so it can override an outer `unless` or a `layerTest(false)`: those narrow the
+   * environment's answer, and the flag is a later, explicit one.
+   *
+   * @param condition - `true` to switch prompting off for `self`
+   */
+  static readonly unless: (condition: boolean) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+}
+//#endregion
+//#region src/CliMessage.d.ts
+/**
+ * Options for {@link CliMessage.status}.
  *
- * So this takes the path core's own `defaultLogger` takes: read the `Console`
- * off the fiber, synchronously. `Console.Console` is a public
- * `Context.Reference`, so it carries a default and never appears in `R`, and a
- * test swaps the reference instead of stubbing a global.
+ * @public
+ */
+interface CliMessageOptions {
+  /**
+   * Where the line goes. Defaults to stderr for a status whose rank is at or above `warning`'s in its
+   * vocabulary, stdout otherwise.
+   */
+  readonly stream?: "stdout" | "stderr" | undefined;
+}
+/**
+ * One-line status messages: a glyph and some text, themed for a person and plain for an agent.
  *
- * @example
- * ```ts
- * import { CliLogger } from "@effected/cli"
- * import { Console, Effect } from "effect"
+ * @remarks
+ * Each line goes through `Console`, `log` for stdout and `error` for stderr, never through the logger, so no
+ * log level can silence it. Only the glyph is painted; the text stays plain. An `agent` audience gets the glyph
+ * and the text and never colour, even when the theme has colour. `success` and `info` go to stdout, `warning`
+ * and `failure` to stderr.
  *
- * const program = Effect.gen(function* () {
- *   yield* Effect.log("synced 3 repos")    // stderr, no timestamp — a diagnostic
- *   yield* Console.log("3 repos synced")   // stdout — the program's actual output
- *   yield* Effect.logError("one failed")   // stderr
- * })
+ * The text is whatever the caller supplies, so it is sanitised: escape sequences and control characters are removed
+ * (a line break is kept as one, a tab becomes a space), as in a document. Under GitHub Actions, where
+ * `CurrentRuntimeEnv` says so, a line the runner would read as a workflow command is neutralized as well. The glyphs
+ * come from the vocabulary, which is configuration, and are not.
  *
- * program.pipe(Effect.provide(CliLogger.layer()))
- * ```
+ * @public
+ */
+export declare class CliMessage {
+  private constructor();
+  /**
+   * Print a status line from a vocabulary.
+   *
+   * @remarks
+   * The stream defaults to stderr when the status ranks at or above `warning` in `vocab`, and stdout
+   * otherwise, so a custom status follows its own rank: a `timeout` ranked 85 goes to stderr.
+   *
+   * @param vocab - the vocabulary the status belongs to
+   * @param name - the status
+   * @param text - the text after the glyph
+   * @param options - the stream override
+   */
+  static readonly status: <N extends string>(vocab: Status<N>, name: N, text: string, options?: CliMessageOptions) => Effect.Effect<void, never, CliTheme | Audience>;
+  /**
+   * A success line, on stdout.
+   *
+   * @param text - the text after the glyph
+   */
+  static readonly success: (text: string) => Effect.Effect<void, never, CliTheme | Audience>;
+  /**
+   * An informational line, on stdout.
+   *
+   * @param text - the text after the glyph
+   */
+  static readonly info: (text: string) => Effect.Effect<void, never, CliTheme | Audience>;
+  /**
+   * A warning line, on stderr.
+   *
+   * @param text - the text after the glyph
+   */
+  static readonly warning: (text: string) => Effect.Effect<void, never, CliTheme | Audience>;
+  /**
+   * A failure line, on stderr.
+   *
+   * @param text - the text after the glyph
+   */
+  static readonly failure: (text: string) => Effect.Effect<void, never, CliTheme | Audience>;
+}
+//#endregion
+//#region src/CliPrompt.d.ts
+/**
+ * Which missing parameter a fallback stands in for, so a non-interactive run can fail with core's own error.
  *
- * @remarks
- * `stderrFrom` defaults to `"All"`: a CLI's stdout is its product, so every
- * log level is a diagnostic unless a consumer narrows the threshold. Write
- * program output with `Console.log`, never `Effect.log`. Pass
- * `stderrFrom: "Error"` for a tool whose output *is* its log lines. This is
- * a breaking change on the 0.x line (#716).
+ * @public
+ */
+type CliPromptTarget = {
+  readonly flag: string;
+} | {
+  readonly argument: string;
+};
+/**
+ * Options for {@link CliPrompt.fallback}.
  *
  * @public
  */
-export declare class CliLogger {
+type CliPromptFallbackOptions<A> = CliPromptTarget & {
+  /** The value to use when the run is not interactive. Without it a non-interactive run fails as missing. */
+  readonly otherwise?: A;
+};
+/**
+ * Prompts that know whether there is a person to ask.
+ *
+ * @public
+ */
+export declare class CliPrompt {
   private constructor();
   /**
-   * The logger itself, for composing into an existing `Logger.layer` set.
+   * A fallback for `Flag.withFallbackPrompt` or `Argument.withFallbackPrompt` that only prompts when the run is
+   * interactive.
    *
    * @remarks
-   * Prefer {@link CliLogger.layer}. Reach for this only when you are building
-   * the logger set yourself and want this one among several.
+   * Interactive (`CliInteractive`): the prompt runs and its answer is used. Not interactive: `otherwise` is used
+   * when given, and the terminal is never read; without it the parameter fails as missing, exactly as it would
+   * with no fallback, so core renders its own message and `CliRuntime.main` exits `64`. Name the parameter with
+   * `flag` (the name without dashes, as given to `Flag.String`) or `argument` so that error can be built.
+   *
+   * Why the prompt runs inside this function rather than being handed back to core: core's
+   * `withFallbackPrompt` turns a quit, such as Ctrl-C, into the original missing-parameter error, which would
+   * exit `64` as if the flag had been forgotten. Here a quit is `Cancelled` with reason `interrupt`, exit `130`.
+   * It is raised as a defect because core's parse step turns every typed failure into a usage error. Core then
+   * runs the already-answered `Prompt.succeed` it is handed. Because it travels as a defect, a handler's
+   * `Effect.catchTag("Cancelled", ...)` cannot see it, and only `CliRuntime.main` (or
+   * `CliRuntime.reportFailures`) renders it as one line with exit `130`; under a bare `runMain` it prints a
+   * stack.
+   *
+   * Pair it with `CliPrompt.gateTerminal`, which `CliEnv.layer` installs: core still runs `Prompt.run` on the
+   * answered prompt it is handed, and `Prompt.run` subscribes the terminal's input, which on a real terminal
+   * attaches a reader to stdin and drops piped input. The gate makes that subscription harmless when the run is
+   * not interactive.
+   *
+   * @param prompt - the prompt to show
+   * @param options - the parameter it stands in for, and the non-interactive default
    */
-  static readonly make: (options?: CliLoggerOptions) => Logger.Logger<unknown, void>;
+  static readonly fallback: <A>(prompt: Prompt.Prompt<A>, options: CliPromptFallbackOptions<A>) => Param.FallbackPrompt<A>;
   /**
-   * Replace the default logger with this one.
+   * Gates core's `Terminal` on `CliInteractive`, so a run that is not interactive never touches the real one.
    *
    * @remarks
-   * `Logger.layer` **replaces** rather than merges, so nothing is emitted twice.
+   * Core's prompt runner subscribes the terminal's input even for a prompt that is already answered, and the
+   * real Node terminal then attaches a readline to stdin, which drops piped input and puts a TTY stdin into raw
+   * mode. Not interactive, this terminal's input is an already-ended queue, its `readLine` fails as quit and its
+   * `display` writes nothing, so any prompt, the wizard included, is quit at once and the real terminal is never
+   * read. Its `columns` and `rows` always come from the real one, so layout keeps working. Interactive, every
+   * call passes through to the real terminal.
    *
-   * Merge this into the layer you provide to the whole program rather than
-   * providing it beneath: merged, it also covers lines emitted during layer
-   * construction, which is exactly where a startup failure prints.
+   * The decision is made on every call, not when the layer is built, so a scope that narrows `CliInteractive`
+   * later, such as an audience flag under `CliAudience.runWith`, gates it too.
+   *
+   * It requires the real `Terminal`. `CliEnv.layer` installs it, after `TerminalEnv` is built from the real
+   * terminal, so consumers do not compose it.
    */
-  static readonly layer: (options?: CliLoggerOptions) => Layer.Layer<never>;
+  static readonly gateTerminal: Layer.Layer<Terminal.Terminal, never, Terminal.Terminal>;
+  /**
+   * Drops core's `--wizard` built-in flag when the run is not interactive.
+   *
+   * @remarks
+   * The wizard prompts, so offering it without a terminal only leads to a dead end. With the flag gone, core
+   * treats `--wizard` as an unknown flag, a usage error that exits `64`, and lists it nowhere in `--help`.
+   * The layer reads `CliInteractive` and the ambient `CliConfig` when it is built, so provide those first, for
+   * example `CliPrompt.gateWizard.pipe(Layer.provide(CliInteractive.layer))`. It filters the ambient `CliConfig`,
+   * so a consumer's own `builtIns` survive, and returns it untouched when interactive. An audience flag read
+   * later is covered by `CliAudience.runWith`, which drops the wizard too. When this layer removes the flag it records
+   * that it did, so `runWith` puts it back only when a flag turns interactivity on where this took it away: a
+   * consumer who never had `Wizard` in their `builtIns` keeps it out.
+   */
+  static readonly gateWizard: Layer.Layer<never>;
 }
 //#endregion
 //#region src/CliRuntime.d.ts
@@ -237,6 +2407,33 @@ interface FailureDetails {
    * failure from the error channel.
    */
   readonly isDefect: boolean;
+  /**
+   * The report the kit writes for this failure when there is no `render`: for this run, in this audience, with its
+   * colour, links and `displayPath`. A `render` that hands a failure back returns these lines unchanged, and the
+   * output is then exactly the default report. It equals `lines()`; to drop the leading status and keep the run's
+   * settings, use {@link FailureDetails.lines} with `status: false`.
+   */
+  readonly defaultLines: ReadonlyArray<string>;
+  /**
+   * The report the kit would write for this failure, rendered for this run: its audience, colour, links and
+   * `displayPath`.
+   *
+   * @remarks
+   * `lines()` is {@link FailureDetails.defaultLines}. With `status: false` the leading status glyph, or the `[FAIL]`
+   * tag in plain text, is left off, so a render that puts its own prefix in front (the program's name, say) reads
+   * cleanly and still gets the run's colour and paths. `CliRuntime.defaultRender` with `status: false` drops the
+   * status too, but it has no run to read and renders plain with absolute paths.
+   *
+   * ```ts
+   * const render = (_error: unknown, details: FailureDetails) =>
+   *   details.lines({ status: false }).map((line, i) => (i === 0 ? `prog: ${line}` : line))
+   * ```
+   *
+   * @param options - `status: false` leaves off the leading status
+   */
+  readonly lines: (options?: {
+    readonly status?: boolean | undefined;
+  }) => ReadonlyArray<string>;
 }
 /**
  * How a failure is turned into output and an exit code.
@@ -245,7 +2442,10 @@ interface FailureDetails {
  */
 interface ReportFailuresOptions {
   /**
-   * Render the failure. Defaults to `String(error)`, one line.
+   * Render the failure. Defaults to the failure's document, `CliFailure.toDoc(cause)`, rendered for the
+   * audience: a failure status line, a tree for a schema failure, a defect's message with its cleaned stack, and
+   * the one fixed line each for `Cancelled` and `NotInteractive`. Under `CliRuntime.main` with `env` it is painted for
+   * a person and plain for an agent or a CI; elsewhere it is plain. It is still written through the logger.
    *
    * @remarks
    * Return several lines to print several: a config error's own message
@@ -256,6 +2456,12 @@ interface ReportFailuresOptions {
    * failure can render as one line and a defect as a full report, without
    * guessing from the error's shape. A renderer that takes only `error`
    * still fits.
+   *
+   * What it returns is text the kit did not build, so the report applies the output policy to it: under GitHub
+   * Actions a line the runner would read as a workflow command is neutralized (with no environment services at all,
+   * always), and for an agent or a CI audience escape sequences are removed (GitHub Actions detects as `ci`). For a person the escapes you return are kept,
+   * since the kit cannot tell your own colour from an injected sequence: a `render` must sanitise the data it
+   * interpolates (an error message, a file name) itself.
    */
   readonly render?: ((error: unknown, details: FailureDetails) => string | ReadonlyArray<string>) | undefined;
   /**
@@ -285,7 +2491,7 @@ interface ReportFailuresOptions {
   readonly usageExitCode?: number | undefined;
 }
 /**
- * Options for {@link CliRuntime.main}.
+ * Options for `CliRuntime.main`.
  *
  * @public
  */
@@ -295,8 +2501,32 @@ interface MainOptions<RP, EP> extends ReportFailuresOptions {
    * on it. Passed in so this package never imports a platform.
    */
   readonly platform: Layer.Layer<RP, EP>;
-  /** The logger, provided outermost. Defaults to `CliLogger.layer()`. */
+  /**
+   * The logger, provided outermost. Defaults to `CliLogger.layer()`, or to `CliLog.layer(env.log)` when
+   * `env.log` is given. An explicit `logger` wins over both.
+   */
   readonly logger?: Layer.Layer<never> | undefined;
+  /**
+   * Provide the environment services, built by {@link CliEnv.layer}, inside failure reporting, where the platform
+   * sits, together with `CliColor.formatterLayer` so help text follows the same colour decision.
+   *
+   * @remarks
+   * The program may then require `CurrentRuntimeEnv`, `TerminalEnv`, `Audience` and `CliTheme` and read
+   * `CliInteractive`. Without it `CliInteractive` keeps its non-interactive default, so forgetting this wiring
+   * gives a CLI that never prompts. With `env.log`, `main` uses `CliLog.layer` as the logger set, and `env.log`
+   * may carry the `file` option when the platform provides `FileSystem` and `Path`. A failure building the env
+   * layer renders as one line and exits through `exitCode`.
+   *
+   * Not interactive, the `Terminal` the program sees is gated: its `readLine` fails as a quit, its input is
+   * already ended and its `display` writes nothing. A program that reads piped data must read `Stdio.stdin`, and
+   * one that writes output must use `Console` or `Stdio`, never `Terminal`.
+   *
+   * Stderr's colour mirrors stdout's terminal check unless `env.stderrIsTerminal` says otherwise, so with stderr
+   * redirected and stdout a terminal the failure report is painted into the file. On Node, pass the real check:
+   * `env: { stderrIsTerminal: Effect.sync(() => process.stderr.isTTY === true) }` (core's `Stdio` reports only
+   * stdout; upstream Effect-TS/effect#8639).
+   */
+  readonly env?: CliEnvOptions | undefined;
   /**
    * Where the help document goes when it is printed with a usage error:
    * `"stdout"` (the default, core's behaviour) or `"stderr"`, beside the
@@ -321,7 +2551,7 @@ interface MainOptions<RP, EP> extends ReportFailuresOptions {
  * Report a CLI program's failures through the program's own logger.
  *
  * @remarks
- * ## The bug this exists to prevent
+ * ## What it prevents
  *
  * A platform `runMain` reports an unhandled failure using Effect's **default**
  * logger. That logger sits **outside** the layers the program was provided —
@@ -338,18 +2568,7 @@ interface MainOptions<RP, EP> extends ReportFailuresOptions {
  *
  * The fix has to happen **inside** the effect, before any `runMain` sees it. So
  * this is a combinator you apply to your program, and you still call your own
- * platform's runner:
- *
- * @example
- * ```ts
- * import { CliRuntime } from "@effected/cli"
- * import { NodeRuntime } from "@effect/platform-node"
- * import { Effect } from "effect"
- *
- * NodeRuntime.runMain(program.pipe(CliRuntime.reportFailures(), Effect.provide(MainLive)))
- * ```
- *
- * Wrapping `runMain` itself would drag a platform choice into a library that
+ * platform's runner. Wrapping `runMain` itself would drag a platform choice into a library that
  * has no business making one, and would make this package unusable from Bun or
  * Deno for no gain.
  *
@@ -392,13 +2611,51 @@ interface MainOptions<RP, EP> extends ReportFailuresOptions {
  * raises is likewise never rendered; it only carries the exit code a
  * successful program recorded through `CliExit`.
  *
+ * @example
+ * ```ts
+ * import { CliRuntime } from "@effected/cli"
+ * import { NodeRuntime } from "@effect/platform-node"
+ * import { Effect } from "effect"
+ *
+ * NodeRuntime.runMain(program.pipe(CliRuntime.reportFailures(), Effect.provide(MainLive)))
+ * ```
+ *
  * @public
  */
 export declare class CliRuntime {
   private constructor();
   /**
-   * Catch, render through the ambient logger, and re-fail with the exit code
-   * and the no-double-report mark.
+   * What `reportFailures` and `main` render a failure as when no `render` option is given, for a consumer's own
+   * `render` to hand a failure back to.
+   *
+   * @remarks
+   * The plain lines of `CliFailure.toDoc(details.cause)`: a failure status line, a `Tree` for a schema failure, a
+   * defect's message with its cleaned `stack`, and the one fixed line each for `Cancelled` and `NotInteractive`.
+   * It has no terminal to ask, so it is the plain rendering for an agent, with absolute paths; the report `main` writes
+   * with no `render` option is the same document in the renderer the audience gets (painted for a person), and that
+   * report is `details.defaultLines`: return those to hand a failure back with the run's colour, links and path
+   * display. With `status: false` the leading status (the glyph, or `[FAIL]` in plain text) is left off, so a prefix
+   * such as the program's name reads cleanly; for that AND the run's settings, use `details.lines({ status: false })`.
+   * A custom `render` that only cares about its own errors delegates the rest:
+   *
+   * ```ts
+   * const render = (error: unknown, details: FailureDetails) =>
+   *   error instanceof MyError ? myLines(error) : CliRuntime.defaultRender(error, details)
+   * ```
+   *
+   * @param error - the squashed failure
+   * @param details - what `render` is told about the failure; accepted so a delegating `render` passes both
+   *   arguments through unchanged (only `cause` and `isDefect` are read)
+   * @param options - `status: false` leaves off the leading status glyph or `[FAIL]` tag
+   */
+  static readonly defaultRender: (error: unknown, details: Pick<FailureDetails, "cause" | "isDefect">, options?: {
+    readonly status?: boolean | undefined;
+  }) => string | ReadonlyArray<string>;
+  /**
+   * Catch a program's failure, render it through the ambient logger, and re-fail with the exit code and the
+   * no-double-report mark.
+   *
+   * @param options - how to render the failure and which exit codes to use
    */
   static readonly reportFailures: (options?: ReportFailuresOptions) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, Error, R>;
   /**
@@ -412,17 +2669,44 @@ export declare class CliRuntime {
    *   fallback code rather than escaping to the runtime's stack trace.
    * - The logger is provided **outermost**, so it is present whichever branch
    *   fails.
+   * - With the `env` option, `CliEnv.layer` and `CliColor.formatterLayer` are
+   *   provided beside the platform, inside failure reporting, so the program can
+   *   read the audience, terminal, theme and `CliInteractive`.
    *
-   * You still call your platform's runner:
+   * You still call your platform's runner.
    *
    * @example
    * ```ts
+   * import { CliRuntime } from "@effected/cli"
+   * import { NodeRuntime, NodeServices } from "@effect/platform-node"
+   * import { Command } from "effect/cli"
+   *
    * NodeRuntime.runMain(
-   *   CliRuntime.main(Command.run(root, { version }), { platform: NodeServices.layer, exitCode: 3 }),
+   *   CliRuntime.main(Command.run(root, { version: "1.0.0" }), { platform: NodeServices.layer, exitCode: 3 }),
    * )
    * ```
+   *
+   * @param program - the CLI program, usually `Command.run(root, { version })`
+   * @param options - the platform layer, and optionally the logger, environment services, exit codes and rendering
    */
-  static readonly main: <A, E, R, RP, EP>(program: Effect.Effect<A, E, R>, options: MainOptions<RP, EP>) => Effect.Effect<void, Error, Exclude<Exclude<R, CliExit>, RP>>;
+  static main<A, E, R, RP, EP>(program: Effect.Effect<A, E, R>, options: MainOptions<RP, EP> & {
+    readonly env?: undefined;
+  }): Effect.Effect<void, Error, Exclude<Exclude<R, CliExit>, RP>>;
+  static main<A, E, R, RP, EP>(program: Effect.Effect<A, E, R>, options: MainOptions<RP, EP> & {
+    readonly env: CliEnvOptions & {
+      readonly log: CliLogFileOptions;
+    };
+  }): Effect.Effect<void, Error, Exclude<Exclude<R, CliExit | CliEnvServices>, RP> | Exclude<Stdio.Stdio | Terminal.Terminal | FileSystem.FileSystem | Path.Path, RP>>;
+  static main<A, E, R, RP, EP>(program: Effect.Effect<A, E, R>, options: MainOptions<RP, EP> & {
+    readonly env: CliEnvOptions & {
+      readonly log?: CliLogOptions & {
+        readonly file?: undefined;
+      };
+    };
+  }): Effect.Effect<void, Error, Exclude<Exclude<R, CliExit | CliEnvServices>, RP> | Exclude<Stdio.Stdio | Terminal.Terminal, RP>>;
+  static main<A, E, R, RP, EP>(program: Effect.Effect<A, E, R>, options: MainOptions<RP, EP> & {
+    readonly env: CliEnvOptions;
+  }): Effect.Effect<void, Error, Exclude<Exclude<R, CliExit | CliEnvServices>, RP> | Exclude<Stdio.Stdio | Terminal.Terminal | FileSystem.FileSystem | Path.Path, RP>>;
   /**
    * Mark an error as already reported, carrying an exit code.
    *
@@ -431,7 +2715,7 @@ export declare class CliRuntime {
    * command that prints its own diagnostics, say — needs the same two marks
    * and should not have to rediscover the inverted polarity.
    *
-   * Under {@link CliRuntime.main} or {@link CliRuntime.reportFailures}, do NOT
+   * Under `CliRuntime.main` or {@link CliRuntime.reportFailures}, do NOT
    * print the failure yourself before failing with it: `reportFailures`
    * renders every error except a `ShowHelp` and a `CliError.UserError` whose
    * reported mark is `false`, so it would print twice. Fail with the marked
@@ -465,35 +2749,21 @@ export declare class CliRuntime {
 //#endregion
 //#region src/ConfigIssueRenderer.d.ts
 /**
- * Render a `@effected/config-file` validation failure.
+ * Turns a `@effected/config-file` `ConfigValidationError` into one line per rejected value.
  *
  * @remarks
  * `ConfigValidationError` carries the structured `issue` tree rather than a
- * string, which is the right design and leaves the consumer holding a tree it
- * has to turn into sentences. This is that step, and it is the same treatment
- * {@link SchemaIssueRenderer} gives a bare issue.
- *
- * **This module is the only thing in the package that references
- * `@effected/config-file`, deliberately.** The peer is declared optional, and
- * an optional peer whose import is reachable from a shared module is not
- * optional — it is a crash for every consumer who took the manifest at its word
- * and did not install it. So nothing else in this package imports this module;
- * only the entrypoint re-exports it, and the shared rendering lives in
- * `internal/format`.
- *
- * The import is additionally `import type`, so it is erased at build time and
- * the runtime reach is **zero** — a consumer without `@effected/config-file`
- * installed can import this module and call `render` on any value without the
- * resolver ever being asked for the package.
- *
- * ## Why this and not just the error's message
- *
- * `ConfigValidationError.message` names the file. It does not name the value,
- * and the difference is the whole diagnostic: a consumer that printed only the
- * message told users "your config is invalid, run the doctor command", and the
- * doctor command — which guessed from a hand-written list of known keys — could
- * only ever find a *misspelling*. A wrongly **shaped** value left the two
- * commands pointing at each other and neither saying what was wrong.
+ * string, so a caller holds a tree it has to turn into sentences. This is that
+ * step, the same treatment {@link SchemaIssueRenderer} gives a bare issue.
+ *
+ * `ConfigValidationError.message` names the file but not the value, and the
+ * value is the diagnostic: printing only the message tells a user their config
+ * is invalid without saying which value is wrong or how it is shaped.
+ *
+ * `@effected/config-file` is an optional peer, and this module only
+ * `import type`s it, so the import is erased at build time. A consumer without
+ * the package installed can import this module without the resolver being asked
+ * for it.
  *
  * @example
  * ```ts
@@ -519,39 +2789,521 @@ export declare class ConfigIssueRenderer {
    *
    * @remarks
    * Takes the **error**, not its `issue`, because that is what a `catchTag`
-   * hands you and because `issue` is typed `Schema.Defect` — reaching into it
-   * at every call site is exactly the ceremony this removes.
-   *
-   * The parameter is the **typed** error rather than `unknown`. An earlier
-   * draft wrote `ConfigValidationError | unknown` to be accommodating, which
-   * collapses to plain `unknown` in TypeScript — so it accepted anything, said
-   * nothing, and left the type import in the `.d.ts` earning nothing. Inside
+   * hands you and because `issue` is typed `Schema.Defect`, which every call
+   * site would otherwise have to reach into. Inside
    * `Effect.catchTag("ConfigValidationError", …)` the error is already this
-   * type, which is where this is called.
+   * type.
    *
-   * It still cannot throw on a malformed value: the issue tree is validated by
+   * It cannot throw on a malformed value: the issue tree is validated by
    * a guard before it is read, so a renderer on an error path never becomes the
    * reason a program dies.
    */
   static readonly render: (error: ConfigValidationError) => ReadonlyArray<string>;
 }
 //#endregion
+//#region src/Fmt.d.ts
+/**
+ * Options for {@link Fmt.truncate}.
+ *
+ * @public
+ */
+interface TruncateOptions {
+  /** Marks the cut; `…` by default. Counted by display width. */
+  readonly ellipsis?: string | undefined;
+}
+/**
+ * Options for {@link Fmt.percent}.
+ *
+ * @public
+ */
+interface PercentOptions {
+  /** Decimal places to round to; `1` by default. A trailing zero decimal is dropped. */
+  readonly digits?: number | undefined;
+  /**
+   * What the input is scaled to: `1` (the default) is a ratio from 0 to 1, `100` is already a percentage from 0
+   * to 100, as istanbul's coverage numbers are.
+   */
+  readonly scale?: 1 | 100 | undefined;
+}
+/**
+ * Small, pure formatting primitives for terminal output.
+ *
+ * @public
+ */
+export declare class Fmt {
+  private constructor();
+  /**
+   * Text made safe to lay out and print, exactly as the renderers make it: complete ANSI and OSC sequences removed,
+   * every other control character removed (a stray ESC, BEL, BS, DEL, the C1 range) except line feed and carriage
+   * return, and a tab turned into a space.
+   *
+   * @remarks
+   * For a `render` or any other text a program builds by hand from data it does not control: an error message, a
+   * file name, a value from the environment. Line breaks are kept, so split on them if the text must be one line.
+   *
+   * @param text - the text
+   */
+  static readonly sanitize: (text: string) => string;
+  /**
+   * The display width of `text` in terminal columns: wide East Asian characters and emoji count two,
+   * combining marks and ANSI escapes count none.
+   *
+   * @param text - the text to measure
+   */
+  static readonly width: (text: string) => number;
+  /**
+   * Cut `text` to at most `width` columns, ending in `ellipsis` when it was cut.
+   *
+   * @remarks
+   * Grapheme-safe: a grapheme, such as a wide character or an emoji ZWJ family, is kept whole or dropped
+   * whole, so the result is never wider than `width`. Text that already fits is returned unchanged, colour
+   * escapes included. Text that must be cut is cut as plain text: its ANSI escapes are dropped rather than cut
+   * in half. When the ellipsis cannot fit, it is omitted and the text is cut to `width`; a `width` of 0 or
+   * less gives `""`.
+   *
+   * @param text - the text to truncate
+   * @param width - the most columns the result may take
+   * @param options - the ellipsis
+   */
+  static readonly truncate: (text: string, width: number, options?: TruncateOptions) => string;
+  /**
+   * A duration in milliseconds as short human text: `250ms`, `1.2s`, `2s`, `1m 3s`, `2m`, `1h 2m`, `2h`.
+   *
+   * @remarks
+   * Under a second it is whole milliseconds; under a minute, seconds to one decimal with a trailing `.0`
+   * dropped; under an hour, minutes and whole seconds, with the seconds dropped when zero; from an hour, hours and
+   * whole minutes, the seconds dropped. A value that rounds up to the next unit (`999.6` to a second, `59999` to a
+   * minute, `3599999` to an hour) is written in that unit, so `1000ms`, `60s` and `60m` never appear. There is no
+   * days unit. A negative or non-finite input is `0ms`.
+   *
+   * @param ms - the duration in milliseconds
+   */
+  static readonly duration: (ms: number) => string;
+  /**
+   * A ratio from 0 to 1 as a percentage, or a number already from 0 to 100 with `scale: 100`: `83.3%`, `50%`,
+   * `100%`.
+   *
+   * @remarks
+   * Rounded to `digits` decimal places (one by default) with trailing zeros dropped, so whole values print
+   * without a decimal. A value that rounds to zero prints `0%`, never `-0%`. The input is not validated.
+   *
+   * @param n - the ratio, 0 to 1 (0 to 100 with `scale: 100`)
+   * @param options - the decimal places and the scale
+   */
+  static readonly percent: (n: number, options?: PercentOptions) => string;
+  /**
+   * A count with its noun: `1 test`, `2 tests`, `0 tests`.
+   *
+   * @param n - the count
+   * @param singular - the noun for exactly one
+   * @param plural - the noun otherwise; `singular` with an `s` appended by default
+   */
+  static readonly plural: (n: number, singular: string, plural?: string) => string;
+}
+//#endregion
+//#region src/GithubAnnotation.d.ts
+/**
+ * The severity of a GitHub annotation.
+ *
+ * @public
+ */
+type AnnotationLevel = "error" | "warning" | "notice";
+/**
+ * What an annotation says about where it points and what it is called.
+ *
+ * @public
+ */
+interface GithubAnnotationProperties {
+  /** `error`, `warning` or `notice`. */
+  readonly level: AnnotationLevel;
+  /** The repository-relative path of the annotated file. */
+  readonly file?: string;
+  /** The first annotated line, 1-based. */
+  readonly line?: number;
+  /** The first annotated column, 1-based. */
+  readonly col?: number;
+  /** The last annotated line. */
+  readonly endLine?: number;
+  /** The last annotated column. */
+  readonly endColumn?: number;
+  /** A short title shown above the annotation. */
+  readonly title?: string;
+}
+/**
+ * GitHub Actions annotations, as workflow commands.
+ *
+ * @public
+ */
+export declare class GithubAnnotation {
+  private constructor();
+  /**
+   * Format an annotation as a workflow command: `::error title=T,file=F,line=1,endLine=2,col=3,endColumn=4::message`.
+   *
+   * @remarks
+   * The message escapes `%`, CR and LF; a property value escapes those and `:` and `,`, per GitHub's
+   * [workflow-command documentation](https://docs.github.com/en/actions/reference/workflow-commands-for-github-actions).
+   * The percent sign is escaped first, so an escape that was just written is never escaped again. An unescaped line
+   * break in a message would let the text after it be read as a new command, which is why the escaping is not optional.
+   *
+   * A property that is not given is left out, and the properties are written in the order `title`, `file`, `line`,
+   * `endLine`, `col`, `endColumn`, the same as `@effected/github-commands`' `WorkflowCommand`, which this renders
+   * through.
+   *
+   * @param annotation - the level and the optional file, position and title
+   * @param message - the annotation's text
+   */
+  static readonly format: (annotation: GithubAnnotationProperties, message: string) => string;
+}
+//#endregion
+//#region src/NotInteractive.d.ts
+declare const NotInteractive_base: Schema.Class<NotInteractive, Schema.TaggedStruct<"NotInteractive", {}>, import("effect/Cause").YieldableError>;
+/**
+ * A command needed to prompt, but there is no terminal to prompt on.
+ *
+ * @remarks
+ * Exits `64` (BSD `EX_USAGE`) through core's `Runtime.errorExitCode` marker:
+ * the caller invoked the command the wrong way, so the fix is to run it in a
+ * terminal or pass the flag that supplies the answer. Its default rendering is
+ * one line, `not interactive: run in a terminal or pass the flag`, which is the error's `message`, so a consumer
+ * `render` can print `error.message` and keep it.
+ *
+ * @public
+ */
+export declare class NotInteractive extends NotInteractive_base {
+  /**
+   * The one line, `not interactive: run in a terminal or pass the flag`.
+   *
+   * @remarks
+   * A prototype getter, not a field, so it is not part of the encoded form, equality or a JSON dump. Assigning to
+   * it is ignored: a library that rewrites `error.message` must not make this error throw, which a getter-only
+   * property does in strict mode. The line is fixed.
+   */
+  get message(): string;
+  set message(_value: string);
+  /**
+   * The process exit code: `64`.
+   *
+   * @remarks
+   * A prototype getter rather than an own field, so a JSON or logger dump of the error does not carry the
+   * runtime marker. It is the error's own code, so `CliRuntime`'s `usageExitCode` option does not change it.
+   */
+  get [Runtime.errorExitCode](): number;
+}
+//#endregion
+//#region src/Render.d.ts
+/**
+ * Everything a renderer needs to know about where its output is going.
+ *
+ * @remarks
+ * A renderer is a pure function of a document and one of these, so two contexts give two renderings of the
+ * same document. `paint` and `link` are plain functions: a context for a stream with no colour passes the
+ * identity, and one whose hyperlinks are off passes a `link` that returns its label unchanged.
+ *
+ * @public
+ */
+interface RenderContext {
+  /**
+   * The display columns available.
+   *
+   * @remarks
+   * `Infinity` is no limit. A renderer clamps what it is given: zero or a negative width is 1, and `NaN` is 80.
+   * `Render.context` gives a human `TerminalEnv.width()`, which is the terminal's columns as stdout reports them, even
+   * for a context built for `"stderr"` (core's `Terminal` has one width); pass `width` to override it.
+   */
+  readonly width: number;
+  /** Who the output is for. */
+  readonly audience: AudienceKind;
+  /** The colour level of the stream being written. */
+  readonly color: ColorLevel;
+  /** Paints text in a token or a style; the identity at colour `none`. */
+  readonly paint: (token: TokenName | Style, text: string) => string;
+  /** The glyph set: status glyphs, separators, the ellipsis. */
+  readonly glyphs: GlyphSet;
+  /**
+   * Wraps a label as a link to a target; returns the label unchanged when links are off.
+   *
+   * @remarks
+   * It must be pure and cheap: a renderer may call it more than once for one link. `Render.ansi` calls it once with
+   * the plain label to learn whether links are on (an unchanged label means off, and the target is then written
+   * after the label), and again when it paints, with the painted label. So it must decide on whether links are
+   * allowed, not on the label's content, and it must not count or record its calls.
+   */
+  readonly link: (target: LinkTarget, label: string) => string;
+  /** Turns an absolute path into its display form; the identity by default. */
+  readonly displayPath: (absolute: string) => string;
+  /**
+   * Whether the output will be read by the GitHub Actions runner, which has two command parsers: a line is a command
+   * if, after .NET whitespace, it starts with `::`, or if `##[` occurs ANYWHERE in it (a bare `##` is not one). When
+   * `true`, `plain`, `ansi` and `markdown` put a zero-width space in front of such a `::` line and between `##` and
+   * `[` at each `##[`, so a document's text, an error message, say, can never inject a command. Unset or `false`
+   * leaves their text alone. `Render.githubLog` ignores it and always neutralizes: its output is for the runner by
+   * definition.
+   *
+   * @remarks
+   * The trigger is the runner, not the audience: a person or an agent whose output lands in an Actions log is read
+   * by it just the same. `Render.context` sets it when `CurrentRuntimeEnv` says GitHub Actions.
+   */
+  readonly neutralizeWorkflowCommands?: boolean | undefined;
+  /**
+   * A base URL for file links in markdown, such as `https://github.com/<owner>/<repo>/blob/<sha>/`. When set,
+   * `Render.markdown` links a `{ file }` target to the base followed by its display path (`displayPath`, URL-encoded,
+   * without a leading `/`) and `#L<line>` when it has a line, in place of a `file://` URL a step summary's reader
+   * cannot open. The other renderers do not read it.
+   */
+  readonly linkBase?: string | undefined;
+}
+/**
+ * Options for {@link Render.contextOf}.
+ *
+ * @public
+ */
+interface RenderContextOfOptions {
+  /** Who the output is for. An `agent` gets no escape of any kind, whatever the other options say. */
+  readonly audience: AudienceKind;
+  /** The colour level; `none` by default, which paints nothing. */
+  readonly color?: ColorLevel | undefined;
+  /** The glyph set; Unicode by default. */
+  readonly glyphs?: GlyphSet | undefined;
+  /** The display columns; unbounded (`Infinity`) by default. */
+  readonly width?: number | undefined;
+  /** Turns an absolute path into its display form; the identity by default. */
+  readonly displayPath?: ((absolute: string) => string) | undefined;
+  /**
+   * Hyperlinks: `off` (the default) leaves every label unlinked; a `CliLinksShape`, such as a `CliLinks` service's
+   * value, makes OSC 8 hyperlinks through {@link CliLinks.linker}, for any audience but an agent.
+   */
+  readonly links?: "off" | CliLinksShape | undefined;
+  /**
+   * See {@link RenderContext.neutralizeWorkflowCommands}. `true` by default for a `ci` audience, whose output the
+   * Actions runner may read (it is harmless elsewhere), and unset for the others; an explicit `false` always wins.
+   */
+  readonly neutralizeWorkflowCommands?: boolean | undefined;
+  /** See {@link RenderContext.linkBase}; unset by default. */
+  readonly linkBase?: string | undefined;
+}
+/**
+ * Options for {@link Render.context}.
+ *
+ * @public
+ */
+interface RenderContextOptions {
+  /**
+   * The display columns to lay out at. By default a human gets `TerminalEnv.width()`, the terminal's columns as
+   * stdout reports them even when the stream is `"stderr"`, and an agent or a CI gets no limit at all.
+   */
+  readonly width?: number | undefined;
+  /** Turns an absolute path into its display form, for example relative to the working directory; the identity by default. */
+  readonly displayPath?: ((absolute: string) => string) | undefined;
+}
+/**
+ * Pure renderers of a document: `(doc, context) => string`.
+ *
+ * @remarks
+ * A renderer has no environment and no effects, so the same document and context always give the same string.
+ * {@link Render.plain} is for agents; the rest of the set follows.
+ *
+ * @example
+ * ```ts
+ * import { Doc, Render } from "@effected/cli"
+ *
+ * const doc = [Doc.heading(2, "Results"), Doc.paragraph("3 checks passed")]
+ * const ctx = Render.contextOf({ audience: "agent" })
+ *
+ * Render.plain(doc, ctx)
+ * // => "Results\n3 checks passed"
+ * ```
+ *
+ * @public
+ */
+export declare class Render {
+  private constructor();
+  /**
+   * The {@link RenderContext} for a stream, from the services a CLI already has.
+   *
+   * @remarks
+   * Everything is read once, here, so the renderers stay pure:
+   *
+   * - `audience` is the `Audience` in force, so an audience flag is honoured;
+   * - `color`, `paint` and `glyphs` are the `CliTheme`'s for THAT stream, so redirecting stdout does not quiet
+   *   stderr; except that an agent's `color` is `none` and its `paint` the identity, so no renderer, `ansi` included,
+   *   writes an escape for an agent whatever the terminal could do;
+   * - `link` is `CliLinks.linker` over that stream's hyperlink support and the audience, so an agent never
+   *   gets an escape and a terminal without OSC 8 gets the label;
+   * - `neutralizeWorkflowCommands` is set when `CurrentRuntimeEnv` says GitHub Actions (read if present, not
+   *   required), for every audience, since the runner reads whatever is written there;
+   * - `width` is the option, else `TerminalEnv.width()` for a human, and **unbounded** (`Infinity`) for an agent
+   *   or a CI, so nothing a reader needs is truncated or wrapped for a terminal that is not there.
+   *
+   * @param stream - the stream the output is for
+   * @param options - an explicit width and a path display function
+   */
+  static readonly context: (stream: "stdout" | "stderr", options?: RenderContextOptions) => Effect.Effect<RenderContext, never, CliTheme | TerminalEnv | Audience | CliLinks>;
+  /**
+   * A {@link RenderContext} from plain options, for a caller outside Effect, such as a test reporter or an Ink tree.
+   *
+   * @remarks
+   * Pure: nothing is read from the environment. The defaults are colour `none`, the identity paint, no links,
+   * Unicode glyphs, unbounded width and the identity `displayPath`, so a context built from an audience alone renders
+   * with no escape of any kind. A colour level paints with the default token styles. An `agent` is colourless and
+   * unlinked whatever `color` and `links` say, as in {@link Render.context}.
+   *
+   * @param options - the audience, and the colour, glyphs, width, path display, links, neutralizing and link base
+   */
+  static readonly contextOf: (options: RenderContextOfOptions) => RenderContext;
+  /**
+   * Render a document as plain text for an agent.
+   *
+   * @remarks
+   * There are no escape sequences of any kind, whatever the context's colour or hyperlinks allow: `paint` and
+   * `link` are never called, and a control character in a document's text is removed. The audience is treated as
+   * `agent`, so a path joins with ` > `.
+   *
+   * - A heading is its text alone, code is in backticks, and a link is its label followed by the target in
+   *   parentheses, as `path:line:col` through `displayPath` for a file, unless the label already is the target.
+   * - A paragraph wraps to the width and is never truncated; a word longer than the width, such as a URL, stays
+   *   whole on its own line.
+   * - A list uses `- ` items, and past its cap the overflow row. A table is aligned text columns with a rule under
+   *   the header; a short row is padded with empty cells, a cell holding line breaks shows its first line and an
+   *   ellipsis, and cells are truncated only when the table is wider than the context, widest column first. A tree uses the glyph set's tree segments.
+   * - A collapsible is its title and the indented body, a callout its upper-case kind and the body, a code block
+   *   four-space indented, and a diff `- expected` lines then `+ received` lines, the cap limiting each side.
+   * - Counts take their total and their visible counters from {@link Doc.total} and {@link Doc.visibleCounters}.
+   *   Inline gives `3/5 passed, 1 failed (1.2s)`: the first counter is the headline and shows its share of the
+   *   total, unless `share` is `false`. Columns gives aligned label and number pairs, and row one line of cells.
+   * - A link with `suffix: false` never has its target after the label, and one with `suffix: true` always does.
+   * - Verbatim text is its lines exactly, each indented by `indent` spaces, never wrapped; an annotation is nothing.
+   * - Strong and emphasised content is its text; a file is its display path, unlinked. `Lines` are one line per entry,
+   *   a `Line` with `truncate` is cut to the width with the ellipsis, and diff text is its lines as given, the cap
+   *   followed by `… N more lines`. A counts table is a table with a column per counter key and the total row last,
+   *   and a counts `suffix` follows the duration.
+   * - A compact list has no blank lines inside an item. A `style: "pipe"` table is istanbul's shape: a rule of dashes
+   *   meeting at `|` above and below the header and at the end, and cells joined with ` | `.
+   * - Top-level blocks are consecutive lines; a section separates its title and children with blank lines.
+   *
+   * @param doc - the document
+   * @param ctx - where the output is going
+   */
+  static readonly plain: (doc: Document, ctx: RenderContext) => string;
+  /**
+   * Render a document for a person: the same layout as {@link Render.plain}, painted and linked.
+   *
+   * @remarks
+   * The context's `paint` and `link` do the styling, so a context at colour `none` with links off gives exactly
+   * what `plain` gives, apart from two things: code has no backticks (it is painted `accent` instead), and a path
+   * joins with the audience's separator (`›` for a person) rather than ` > `. Tokens:
+   *
+   * - headings, section and collapsible titles, and table headers are `emphasis`; the rule under a header, tree
+   *   lines and overflow rows are `muted`;
+   * - a status glyph takes its definition's token, and a diff's `-` lines are `failure` and `+` lines `success`;
+   * - a callout's label takes its kind's token (`note` info, `tip` success, `important` accent, `warning` warning,
+   *   `caution` error), and a counter the token of its status, with the qualifier, the duration and the suffix `muted`.
+   *   A `Counts` with `paint: "none"` paints none of it, and with `paint: "glyph"` only a status glyph.
+   * - strong content is bold and emphasised content italic, over any token it has; in diff text a `+` line is
+   *   `success` and a `-` line `failure`; a counts table's counts take their status's token.
+   *
+   * A link goes through `ctx.link`, which makes an OSC 8 hyperlink only when the policy allows it. When it does
+   * not (it returns the label unchanged), the target follows the label in parentheses, muted, as in plain text.
+   *
+   * Text is cut and wrapped before it is painted, so a colour or a hyperlink is never cut in half, and a table
+   * cut to the width keeps the colour of what remains. Tables are plain aligned columns, never box drawing:
+   * box drawing costs two columns of every row for nothing a rule and the padding do not already say, and it
+   * cannot be matched to plain text.
+   *
+   * @param doc - the document
+   * @param ctx - where the output is going
+   */
+  static readonly ansi: (doc: Document, ctx: RenderContext) => string;
+  /**
+   * Render a document as GitHub-flavoured markdown, for a step summary or a file.
+   *
+   * @remarks
+   * There is no ANSI and no OSC 8 (`paint` and `link` are never called), and the width does not apply: a reader
+   * wraps. Everything a document carries as text is escaped so that it cannot become markdown: the characters
+   * that mean something, `|` everywhere so text can never form a table, the marker at the start of a line (a
+   * heading, bullet, setext underline or ordered item) and the start of an autolink (a URL scheme or `www.`). An
+   * email address is not escaped: a reader may make a `mailto:` link of it, which is harmless. A leading indent is
+   * dropped, since markdown would read it as code.
+   *
+   * Under GitHub Actions (`neutralizeWorkflowCommands`) the same neutralizing applies, since markdown can be printed
+   * to the log. Markdown escapes `[` in text, so `##[` cannot appear outside code and the headings are untouched
+   * (a bare `##` is not a command); code spans and blocks, which are not escaped, get the zero-width space, which can
+   * also land inside code or table text where it would otherwise have formed a command.
+   *
+   * GitHub also turns `@user`, `@org/team`, `#123` and commit SHAs in rendered markdown into mentions and references.
+   * Nothing here escapes them: in a step summary they do not notify, but markdown posted as a comment could ping
+   * whoever the text names.
+   *
+   * - A heading is `#` repeated by its level. A section's title is a heading of level 2 for a section at the top,
+   *   one deeper for each section nested inside it, to level 6.
+   * - A table is a GFM pipe table: `|` is `\|` in a cell and a line break in a cell is `<br>`. A short row is
+   *   padded and a long one widens the table. With no header, the header row is empty.
+   * - A collapsible is `<details><summary>title</summary>`, a blank line, the body as markdown, a blank line and
+   *   `</details>`. The title is HTML, so it is HTML-escaped and plain.
+   * - A callout is a quoted `[!KIND]` followed by its body. A code block is a fence longer than any backtick run it
+   *   holds, and a diff a `diff` fence of `-` and `+` lines.
+   * - A link is `[label](url)` when it has a URL a reader can follow: an `http`, `https`, `mailto`, `file` or
+   *   `vscode` URL, or a relative one. A file link has one when its path is absolute (`file://`). Otherwise, such as
+   *   for a `javascript:` URL or a relative file path, it is the label followed by the target in inline code, as
+   *   `path:line:col` for a file.
+   * - A list is bullets, a tree a nested bullet list under its root label, and overflow rows paragraphs after what
+   *   they cap. Counts inline is a paragraph, columns a list of `label: n` and row a one-row table of the counter
+   *   labels over their numbers, every header named (the duration as `duration`), with the label above the table and
+   *   the qualifier and suffix below it.
+   * - Verbatim text is a fenced code block, so its indentation survives; an annotation is nothing.
+   * - Strong content is `**…**` and emphasised `*…*`, which GFM reads inside a word too, with the spaces at a run's
+   *   edges kept outside the markers. `Lines` are one paragraph with a hard break between entries, an empty entry
+   *   between two others an empty line (one at either end is dropped); a `Line` is one
+   *   paragraph; diff text a `diff` fence; a counts table a pipe table; a file is its display path as text.
+   * - With `linkBase`, a file link goes to the base and the display path, plus `#L<line>`, in place of `file://`. A
+   *   display path that is absolute or climbs out with `..` is not under the base, so its link has no URL form.
+   * - A compact list item joins its parts with no blank line, putting a hard break where two paragraphs would merge.
+   *   A row of counts names its duration column `duration`.
+   *
+   * @param doc - the document
+   * @param ctx - where the output is going; its glyph set, audience and `displayPath` are used
+   */
+  static readonly markdown: (doc: Document, ctx: RenderContext) => string;
+  /**
+   * Render a document for a GitHub Actions log.
+   *
+   * @remarks
+   * Everything is what {@link Render.plain} renders, except an annotation, which is one workflow command
+   * (`::error file=…,line=…::message`), and a collapsible that starts a line, which is a group: `::group::title`, its
+   * body, `::endgroup::`. An annotation is a command at the top level, as a top-level section's child, and as a direct
+   * child of a group's body; anywhere deeper (inside a list, a callout, or a section within a group) it is nothing,
+   * as in plain. Its message and properties are escaped, so no text can end
+   * the command or start another, and the kit's own command is never neutralized. That is a top-level collapsible, or one that is a direct child of a
+   * top-level section. GitHub does not nest groups, so a collapsible inside a group, or inside a list or callout
+   * (where it would not start a line), keeps plain's rendering: its title on a line and its body indented.
+   *
+   * The runner has two command parsers, and a line is a command if either accepts it: after its leading whitespace it
+   * starts with `::`, or `##[` occurs ANYWHERE in it (a bare `##` is not one). A document's text must not be able to
+   * do that (`::add-mask::`, `::error::`, `##[error]`), so such a `::` line gets a zero-width space in front, which
+   * the runner does not treat as whitespace, and every `##[` gets one between the `##` and the `[`. The text is
+   * otherwise unchanged. A
+   * group's title is a command's data, so its `%`, CR and LF are escaped. Lines are split at CR, LF and CRLF before
+   * that check, as the runner splits them. There is no ANSI and `paint` and `link` are never called, and the audience
+   * is treated as `agent`, as `plain` does.
+   *
+   * @param doc - the document
+   * @param ctx - where the output is going; the width, glyph set and `displayPath` are used as plain uses them
+   */
+  static readonly githubLog: (doc: Document, ctx: RenderContext) => string;
+}
+//#endregion
 //#region src/SchemaIssueRenderer.d.ts
 /**
- * Turn a `SchemaIssue` tree into lines a user can act on.
+ * Turns a `SchemaIssue` tree into lines a user can act on.
  *
  * @remarks
  * A decode failure arrives as a structured tree; a person needs
- * `unknown key at groups.g.cleanup.rulesetz`.
+ * `unknown key at groups.g.cleanup.rulesetz`. The formatters core ships for
+ * this live on `SchemaIssue` rather than on `SchemaError` or `Schema`, and
+ * `SchemaError.message` does not use them, so printing the error alone does not
+ * give these lines.
  *
- * **Core already ships the formatters this wraps, and they are effectively
- * undiscoverable.** They live on `SchemaIssue` rather than `SchemaError` or
- * `Schema`, they are named `makeFormatter*` rather than anything containing
- * "render" or "format issue", and `SchemaError.message` does not use them — so
- * the obvious probe, printing the error, hints at nothing. Two engineers
- * searched for two rounds and concluded core had none. This export exists to
- * end that search, and the one phrasing override is a bonus rather than the
- * point.
+ * The lines and `CliFailure`'s tree are two views of the same rejected values (`internal/format`), so a schema
+ * failure in the default report and these lines never disagree.
  *
  * @example
  * ```ts
@@ -583,5 +3335,5 @@ export declare class SchemaIssueRenderer {
   static readonly render: (issue: unknown) => ReadonlyArray<string>;
 }
 //#endregion
-export type { CliExitShape, CliLoggerOptions, FailureDetails, MainOptions, ReportFailuresOptions };
+export type { AnnotationLevel, AnnotationOptions, AudienceFlagInput, Block, BlockOf, CliAudienceFlagsOptions, CliDocSource, CliEnvOptions, CliEnvServices, CliEnvTestOptions, CliEnvTestServices, CliExitShape, CliFailureOptions, CliLinksLinkerOptions, CliLinksOptions, CliLinksShape, CliLogFile, CliLogFileOptions, CliLogOptions, CliLoggerOptions, CliMessageOptions, CliPromptFallbackOptions, CliPromptTarget, CliThemeOptions, CliThemeShape, CliThemeTestOptions, Column, CoreStatusName, Counter, CountsOptions, CountsRow, CountsTableOptions, DocPrintOptions, Document, EditorLinks, FailureDetails, GithubAnnotationProperties, GlyphSelectOptions, GlyphSet, Inline, InlineInput, InlineOf, LinkOptions, LinkTarget, ListOptions, MainOptions, NamedColor, OverflowOptions, PercentOptions, RenderContext, RenderContextOfOptions, RenderContextOptions, ReportFailuresOptions, RequiresAudienceFlags, StatusDef, StatusRef, StreamTheme, Style, TableOptions, TokenName, TreeInput, TreeNode, TruncateOptions };
 //# sourceMappingURL=index.d.ts.map