@effected/cli-kit 0.0.0-stage → 0.27.0

package/index.d.ts

@@ -0,0 +1,4035 @@
+import { Array as Array$1, Cause, Context, Duration, 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 { Distribution } from "@effected/kit";
+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;
+}
+/**
+ * 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>;
+}
+/**
+ * How subcommand help renders flags the command does not own, as core's `CliOutput.defaultFormatter` takes them.
+ *
+ * @remarks
+ * `inheritedFlags` covers flags a parent command shares with its subcommands (for example `CliAudience.flags()`);
+ * `globalFlags` covers the built-ins such as `--help` and `--version`. Each is `"full"` (core's default, every flag
+ * listed), `"summary"` (a one-line pointer) or `"none"`.
+ *
+ * @public
+ */
+interface CliHelpFlags {
+  readonly inheritedFlags?: "full" | "summary" | "none" | undefined;
+  readonly globalFlags?: "full" | "summary" | "none" | undefined;
+}
+/**
+ * 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.
+   *
+   * `helpFlags` sets how subcommand help renders the flags a parent declared (`inheritedFlags`) and the
+   * program-wide built-ins (`globalFlags`): `"full"` (core's default), `"summary"` or `"none"`. It is passed to
+   * core's `defaultFormatter` beside the colour decision, so choosing a mode costs no colour.
+   *
+   * 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>, helpFlags?: CliHelpFlags) => Layer.Layer<never, never, Stdio.Stdio>;
+}
+/**
+ * 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;
+}
+/**
+ * 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. It is theme-blind: it knows only the default palette and the `overrides` you pass, never a mounted
+   * theme, so a component under `CliUi` that wants the screen's theme uses `useStyle`. 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;
+}
+/**
+ * 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-kit"
+ *
+ * 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. The glyph is sanitised, as text in a document is: escape
+   * sequences and control characters in a vocabulary's glyph are removed, so a glyph built from data cannot paint the
+   * terminal, plant a hyperlink or move the cursor. Every kit path that draws a status glyph takes it from here.
+   *
+   * @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>;
+}
+/**
+ * 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, sanitised (see `Status.glyph`) and painted with its token, then
+   * `text` when given, as it is: sanitising `text` is the caller's, as `CliMessage` and `CliLog.status` do.
+   */
+  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-kit/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>;
+  /**
+   * The theme an audience sees of `theme`: for an agent, the same theme at colour `none` (`paint` the identity, `sgr`
+   * empty, `status` unpainted), whatever the terminal could do, because an agent never gets an escape of any kind; for
+   * anyone else, or when the audience is not known, `theme` itself.
+   *
+   * @remarks
+   * The one rule the kit applies wherever it paints for an audience: `Render.context` takes its colour and `paint`
+   * from it, `CliMessage` and `CliLog.status` paint their glyphs through it, and `./ui` gives it to the trees it
+   * mounts, so `useTheme`, `Styled` and the widgets' colour-`none` text markers all agree. A program that paints its
+   * own lines applies the same rule with it rather than re-implementing it:
+   *
+   * ```ts
+   * const line = Effect.gen(function* () {
+   *   const theme = CliTheme.forAudience((yield* CliTheme).forStream("stdout"), (yield* Audience).kind)
+   *   return theme.status(Status.core, "success", Fmt.sanitize(name))
+   * })
+   * ```
+   *
+   * Pure: it reads nothing, so the audience is the caller's to pass, `undefined` when it is not known.
+   *
+   * @param theme - a stream's theme, such as `CliTheme.forStream("stdout")`
+   * @param audience - who the output is for, or `undefined` when that is not known
+   */
+  static readonly forAudience: (theme: StreamTheme, audience: AudienceKind | undefined) => StreamTheme;
+  /**
+   * 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`, and `colors` is the theme's
+   * own decision (`false` at `none`), so core's prompts and its command wizard write no colour or style escape, not
+   * even a reset, and core never re-reads the host for `NO_COLOR` or a TTY. Cursor and redraw controls are still
+   * written, whatever the theme says. Under ASCII glyphs the prompt symbols fall back to ASCII too.
+   */
+  static readonly promptTheme: Layer.Layer<never, never, CliTheme>;
+}
+/**
+ * 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: one label, or a singular and a plural form, `one` for a count of exactly 1
+   * and `other` for any other, 0 included. The count is the counter's own `n`, except in a share headline
+   * (`1/3 repos`), which reads by the total. A `CountsTable` heads its column with `other`, since the column holds
+   * every row's count.
+   */
+  readonly label: string | {
+    readonly one: string;
+    readonly other: 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, and `wrap: false` keeps whole.
+ * - `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 truncate?: boolean;
+  readonly wrap?: boolean;
+} | {
+  readonly _tag: "Line";
+  readonly content: ReadonlyArray<Inline>;
+  readonly truncate?: boolean;
+  readonly wrap?: 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-kit"
+ *
+ * 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.
+   *
+   * @remarks
+   * The children are separated by blank lines (unless the document is compact); a title sits directly above the first.
+   * `Doc.section(undefined, blocks)` is the way to space a document's top-level blocks, which are otherwise joined with
+   * no blank line.
+   *
+   * @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.
+   *
+   * The label is one string, or `{ one, other }` to pluralise by count: `one` when the count is exactly 1 and `other`
+   * for every other count, 0 included. A count standing alone reads by its own `n` (`1 change`, `2 changes`); a
+   * headline shown as a share of the total reads by that total, the noun it counts (`1/1 repo`, `1/3 repos`,
+   * `2/3 repos`).
+   *
+   * @param vocab - the vocabulary the status belongs to
+   * @param name - a status name in it
+   * @param options - the counter's `key`, its `label` (one string, or `{ one, other }`), its 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 one: string;
+      readonly other: 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.
+   *
+   * @remarks
+   * `truncate` and `wrap: false` hold for every entry as they do for {@link Doc.line}: each entry is cut to the width,
+   * or kept whole on one line, rather than wrapped. Markdown keeps every entry whole either way.
+   *
+   * @param lines - the entries; each takes a string, an inline or an array of either
+   * @param options - `truncate`, to cut each entry to the width; `wrap: false`, to keep each whole
+   */
+  static lines(lines: ReadonlyArray<InlineInput>, options?: {
+    readonly truncate?: boolean;
+    readonly wrap?: boolean;
+  }): BlockOf<"Lines">;
+  /**
+   * One line of content; with `truncate`, it is cut to the width with the glyph set's ellipsis instead of wrapping,
+   * and with `wrap: false` it is kept whole on one line whatever the width.
+   *
+   * @remarks
+   * By default a line longer than the width wraps. `wrap: false` keeps it atomic in every audience and renderer, still
+   * carrying its status glyphs, theme tokens and links, which {@link Doc.verbatim} (a plain string) cannot: the tool for
+   * a finding such as `✗ path:line:col  rule  message` that a reader greps or reads line by line, while the prose around
+   * it still wraps. A line break inside it is still a space. With both `truncate` and `wrap: false`, `truncate` wins:
+   * the line is cut to the width.
+   *
+   * @param content - the line
+   * @param options - `truncate`, to cut it to the width; `wrap: false`, to keep it whole
+   */
+  static line(content: InlineInput, options?: {
+    readonly truncate?: boolean;
+    readonly wrap?: 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 the command itself; its message and properties are
+   * escaped, so no text in them can end the command or start another, and a `##[` in its message, title or file gets
+   * a braille pattern blank (U+2800) before the `[`, as in plain text. 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, a CI, and a human whose stream is not a terminal.
+   *
+   * 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.
+   *
+   * The whole document is written as one `Console.log` (or `Console.error`) call, with its line breaks embedded, so a
+   * captured `Console` holds one entry per document, not one per line. Top-level blocks are joined with no blank
+   * line between them; wrap them in `Doc.section(undefined, [...])` to space them.
+   *
+   * `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.
+   *
+   * The context is built here, at print time, so it carries the fiber's count of open Actions log groups
+   * (`RenderContext.groupDepth`): printed inside an `ActionLogger.group` from `@effected/github-actions`, a
+   * document's top-level collapsible renders as plain text rather than as a second `::group::`, which would end
+   * the open one at the runner.
+   *
+   * @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>;
+}
+/**
+ * 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-kit/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;
+}
+/**
+ * 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-kit"
+ * 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>;
+}
+/**
+ * Options for `CliLog.status`.
+ *
+ * @public
+ */
+interface CliLogStatusOptions {
+  /**
+   * The level the line is logged at. By default it follows the status's rank in its vocabulary: `Error` at or above
+   * `failure`'s rank, `Warn` at or above `warning`'s, and `Info` below that.
+   */
+  readonly level?: LogLevel.Severity | undefined;
+  /**
+   * What the line starts with, before the glyph, so an indented report line keeps its place in a block: a number of
+   * spaces (floored, at most 64; zero, a negative or a non-finite number is none), or a string. A string is sanitised as text is (escapes and controls removed, a tab a space) and its line
+   * breaks dropped, so the indent can never carry an escape onto the trusted line. None by default.
+   */
+  readonly indent?: number | string | undefined;
+}
+/**
+ * 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
+ * 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-kit"
+ * 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 CliLog {
+  private constructor();
+  /**
+   * The diagnostics threshold. Defaults to `None`, silent.
+   *
+   * @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 Level: Context.Reference<LogLevel.LogLevel>;
+  /**
+   * Read a log level the way `CliLog.layer` reads its environment variable: `Option.some` of the level, or
+   * `Option.none()` when the text is not one.
+   *
+   * @remarks
+   * Case-insensitive, and not trimmed. The spellings are `all`, `trace`, `debug`, `info`, `warn` (or `warning`),
+   * `error`, `fatal` and `none`. For a host that reads a level from its own flag or config and wants the same answer
+   * the layer would give.
+   *
+   * @example
+   * ```ts
+   * CliLog.parseLevel("WARNING") // Option.some("Warn")
+   * CliLog.parseLevel("loud") // Option.none()
+   * ```
+   *
+   * @param text - the level's spelling
+   */
+  static parseLevel(text: string): Option.Option<LogLevel.LogLevel>;
+  /**
+   * The whole logger set of a program: a `CliLogger` for ordinary lines plus the diagnostics sink.
+   *
+   * @remarks
+   * 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 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.
+   *
+   * 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 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>;
+  /**
+   * Log a status line: its glyph painted through the theme, then `text`, at a level that follows the status.
+   *
+   * @remarks
+   * The line goes through the logger, so it is a diagnostic like any `Effect.log*` call: filtered by the level in
+   * force (`--log-level`, `CliLog.Level`), routed by `CliLogger`'s `stderrFrom` (stderr by default) and neutralized
+   * under GitHub Actions. What differs is the glyph: the logger sanitises every line a program logs, which strips a
+   * colour a program painted itself, so a glyph on the log channel was always drawn bare. Here the kit paints it and
+   * marks the line as its own, so the plain `CliLogger` line keeps the colour, while `text` is still sanitised:
+   * escape sequences and control characters in it are removed, as in every line the kit writes.
+   *
+   * The glyph is painted with stderr's theme (where diagnostics go) through {@link CliTheme.forAudience}, so an agent
+   * gets it unpainted, and an `Audience` is read only when provided, so it stays out of the requirements. ASCII glyphs
+   * give the status's ASCII form. A diagnostics record carries the line as its message as any record does: the `CliLog`
+   * sink's pretty line sanitises it (the glyph is drawn bare there), and NDJSON keeps it, JSON-escaped.
+   *
+   * The level defaults to the status's rank in `vocab`: `Error` at or above `failure`'s, `Warn` at or above
+   * `warning`'s, `Info` below, so a custom status follows its own rank. Pass `level` to choose it, and `indent` (a
+   * number of spaces, or a string, sanitised) to start the line inside an indented block: `    ✗ error   x: red`.
+   *
+   * @example
+   * ```ts
+   * import { CliLog, Status } from "@effected/cli-kit"
+   *
+   * // ✗ in the failure colour, then the message: on stderr, filtered by the log level.
+   * const reportError = (resource: string, message: string) =>
+   *   CliLog.status(Status.core, "failure", `${resource}: ${message}`)
+   * ```
+   *
+   * @param vocab - the vocabulary the status belongs to
+   * @param name - the status
+   * @param text - the text after the glyph, sanitised
+   * @param options - the level to log at, and the indent before the glyph
+   */
+  static readonly status: <N extends string>(vocab: Status<N>, name: N, text: string, options?: CliLogStatusOptions) => Effect.Effect<void, never, CliTheme>;
+  /**
+   * 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>;
+}
+/**
+ * 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; omitted, core's `Stdio.stderrIsTerminal` answers.
+   *
+   * @remarks
+   * The platform `Stdio` reads the host (`process.stderr.isTTY` on Node), so a program whose stdout is a terminal
+   * but whose stderr is redirected to a file writes its failure report and warnings there unpainted, with nothing
+   * passed here. A `Stdio` built with `Stdio.make` without the field answers `false`; pass this only for a host
+   * whose `Stdio` cannot say.
+   */
+  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;
+  /**
+   * How subcommand help renders flags it does not own, passed to core's `CliOutput.defaultFormatter` beside the
+   * colour decision. Only `CliRuntime.main` reads this.
+   *
+   * @remarks
+   * `inheritedFlags` covers flags a parent command shares with its subcommands (for example `CliAudience.flags()`);
+   * `globalFlags` covers the built-ins such as `--help` and `--version`. Each is `"full"` (core's default, every flag
+   * listed), `"summary"` (a one-line pointer) or `"none"`. Setting a mode here keeps the kit's colour decision, which
+   * supplying your own `formatHelpDoc` through {@link CliEnvOptions.formatter} would lose.
+   */
+  readonly helpFlags?: CliHelpFlags | undefined;
+  /**
+   * How an absolute path is shown: a function, or `{ relativeTo: root }` to show a path under `root` relative to it.
+   * The identity by default.
+   *
+   * @remarks
+   * It is every path the kit shows for this run: `Render.context` takes it as its default, so `Doc.print`, a
+   * `Doc.path` or file link, and a live view's `final` document follow it, and so do the stack frames of the default
+   * failure report. An explicit `displayPath` passed to `Doc.print` or `Render.context` still wins.
+   *
+   * `{ relativeTo: root }` takes an absolute `root`. A path under it is shown relative to it; `root` itself, and a path
+   * outside it, are shown absolute, since a `../..` chain says less than the absolute path. It uses the `Path` service
+   * when the platform provides one (as `CliRuntime.main`'s does), and otherwise a plain prefix test on `/` and `\`.
+   */
+  readonly displayPath?: ((absolute: string) => string) | {
+    readonly relativeTo: 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;
+  /**
+   * Which spans the default failure report's `in: outer › inner` trail names: `app`, the default, leaves out the spans
+   * the kit's own packages and Effect define (judged by the file of each span's definition site under `node_modules`),
+   * `all` shows every span, and `off` drops the trail. Applies to the report `main` writes,
+   * `FailureDetails.defaultLines` and `FailureDetails.lines`. Only `CliRuntime.main` reads this.
+   */
+  readonly spans?: "app" | "all" | "off" | undefined;
+  /**
+   * The environment variable that sets `spans` at run time (`app`, `all` or `off`, case-insensitive), read through
+   * `Config`, as `log.envVar` sets the log level: so a user filing a bug can run `TOOL_SPANS=all tool …` without a
+   * rebuild. `spans` beats it (the variable is then not read at all); unset or empty is the default; a value that is
+   * not a setting is ignored with one warning. Not read unless named. Only `CliRuntime.main` reads this.
+   */
+  readonly spansEnvVar?: string | undefined;
+  /**
+   * A module of the running program itself, as a `file:` URL or an absolute path: pass the bin's `import.meta.url`.
+   * `spans: "app"` keeps the spans of the package that holds it, even when it is installed under
+   * `node_modules/@effected/` (a kit companion's bin); see `CliFailureOptions.appModule`. Only `CliRuntime.main`
+   * reads this.
+   */
+  readonly appModule?: string | 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.
+ *
+ * It sets core's `TerminalCapabilities` from `TerminalEnv` (through `TerminalEnv.capabilities` in `@effected/env`), so
+ * the colour of core's own help, version and error output follows the kit's colour rule, and `canAnimate` is stdout
+ * being a terminal that is not `dumb`. `canPrompt` alone is held at `true` whatever the terminal is: core skips a
+ * fallback prompt entirely when it is `false`, which would lose `CliPrompt.fallback`'s and `CliUi.fallback`'s
+ * `otherwise` in every piped run, and `CliInteractive` with `CliPrompt.gateTerminal` already owns that decision (the
+ * gate quits any other prompt at once when the run is not interactive). A `TerminalCapabilities` with
+ * `canPrompt: false` provided inside the program bypasses the kit's fallbacks: the parameter then fails as missing even
+ * when an `otherwise` is given.
+ *
+ * @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`), and core's `TerminalCapabilities` from them as `CliEnv.layer` sets it, `canPrompt` held at `true`.
+   *
+   * @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-kit/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>;
+}
+/**
+ * The shape behind {@link CliExit}.
+ *
+ * @public
+ */
+interface CliExitShape {
+  /** The highest exit code recorded during the run; `0` until one is set. */
+  readonly code: MutableRef.MutableRef<number>;
+}
+declare const CliExit_base: Context.ServiceClass<CliExit, "@effected/cli-kit/CliExit", CliExitShape>;
+/**
+ * The exit code a successful run wants, for commands whose findings are a
+ * result rather than a failure (a linter that found problems, say).
+ *
+ * @remarks
+ * Findings are not a failure — a JSON `tapError` must not fire, and the
+ * 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. `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.
+ *
+ * A `Service`, not a `Reference`: forgetting `CliRuntime.main` is a type error,
+ * never a silently ignored global.
+ *
+ * @public
+ */
+export declare class CliExit extends CliExit_base {
+  /**
+   * A fresh cell at `0`; `CliRuntime.main` provides it, and tests provide it
+   * directly.
+   *
+   * @remarks
+   * Every provide mints a new cell. Layers memoize by reference across
+   * `Effect.provide` calls, so without `Layer.fresh` a second provide of this
+   * layer anywhere in the program — a nested `CliRuntime.main`, a test
+   * helper — would silently share the first run's cell and inherit its code.
+   *
+   * A program run under `CliRuntime.main` must NOT provide `CliExit.layer`
+   * itself: `main` already provides one, and a second provide mints a second,
+   * unrelated cell that `main` never reads back, so `CliExit.set` calls made
+   * against it are silently discarded and the run exits `0`.
+   */
+  static readonly layer: Layer.Layer<CliExit>;
+  /**
+   * Record an exit code; the highest code set during the run wins.
+   *
+   * @remarks
+   * Highest-wins, not last-wins, so a later "clean" step cannot quietly
+   * downgrade an earlier finding's code.
+   *
+   * The code must be an integer in `0..255` — the range a POSIX exit status
+   * can carry. Anything else dies as a defect naming the value: `256` would
+   * wrap to exit `0` and silently pass a run with findings, and a fraction
+   * such as `1.5` makes `process.exit` throw `ERR_OUT_OF_RANGE` after the
+   * program has finished.
+   *
+   * The code only applies to a run that **succeeds**. A program failure beats
+   * findings: when the program fails, `CliRuntime.main` never reads this
+   * cell, and the failure's own exit code (or the `exitCode` fallback) wins.
+   */
+  static readonly set: (code: number) => Effect.Effect<void, never, CliExit>;
+  /**
+   * Write one line to stderr, record an exit code, and succeed: the shape of a
+   * hook-style command that must say why it exits non-zero without failing.
+   *
+   * @remarks
+   * This does **not** stop the program. It succeeds, so the caller must still
+   * return (or otherwise end its own flow) after calling it; finalizers and log
+   * sinks run as they would on any successful run, and `CliRuntime.main` turns
+   * the recorded code into the exit.
+   *
+   * The code is validated first, exactly as {@link CliExit.set} validates it, and
+   * an invalid code dies as the same defect before anything is written. The
+   * line goes through `Console.error`, never stdout, and is written as given:
+   * sanitize anything you do not control with `Fmt.sanitize` first. The
+   * highest code recorded during the run wins.
+   */
+  static readonly report: (code: number, line: string) => Effect.Effect<void, never, CliExit>;
+  /**
+   * Report a failure cause as one stderr line, record the exit code the caller
+   * chooses for it, and succeed.
+   *
+   * @remarks
+   * The cause is squashed and the line is `<code> <tag>: <message>`, or
+   * `<code> <message>` when the error has no string `_tag`. The message comes
+   * from `Fmt.errorText` and is sanitized with `Fmt.sanitize` and its line breaks
+   * become a space, so a hostile error can neither throw, write an escape nor
+   * forge a second line. Reading `_tag` is guarded
+   * too: a getter that throws means no tag.
+   *
+   * An interrupt-only cause is not a failure to report: nothing is written or
+   * recorded and the effect re-interrupts. `codeOf` receives the squashed error
+   * and must return an integer in `0..255`; anything else dies as
+   * {@link CliExit.set} does, which is wiring.
+   *
+   * Like {@link CliExit.report} it does not stop the program: the caller still
+   * has to return.
+   */
+  static readonly reportCause: <E>(cause: Cause.Cause<E>, codeOf: (error: unknown) => number) => Effect.Effect<void, never, CliExit>;
+}
+/**
+ * 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
+ */
+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 {
+  /**
+   * 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?: 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;
+  /**
+   * 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 stackFrames?: "app" | "all" | undefined;
+  /**
+   * Which spans the `in: outer › inner` trail after a failure names. `app`, the default, leaves out the spans the kit
+   * and Effect define themselves: a span whose definition site (an `Effect.fn`'s, or where the span was opened) is a
+   * file under `node_modules/@effected/` or `node_modules/effect/`. A config that fails to decode under
+   * `@effected/config-file` then reports no `ConfigFile.loadFrom` trail, while the program's own spans stay. `all`
+   * shows every span, and `off` drops the trail. Under either, an `Effect.fn` call and its definition are one entry,
+   * `name`, never `name (definition) › name`.
+   *
+   * @remarks
+   * The rule reads file paths, never span names, and it fails open: when it cannot tell, it shows the span. A span
+   * with no captured stack is kept. A kit package linked into a workspace (`link:`, `workspace:`) runs from its own
+   * checkout rather than from `node_modules`, so its spans show as the program's. A bundled program is one file, so
+   * `app` shows what `all` does, unless the bundle is itself installed under `node_modules/@effected/`. A program that
+   * is installed under `node_modules/@effected/` (a kit companion's bin) names itself with `appModule`, or its own
+   * spans are left out with the kit's.
+   */
+  readonly spans?: "app" | "all" | "off" | undefined;
+  /**
+   * A module of the running program itself, as a `file:` URL or an absolute path: its bin's `import.meta.url`. With
+   * `spans: "app"`, a span defined in the installed package that holds this module is the program's, kept even under
+   * `node_modules/@effected/`, while the packages it depends on (beside it, or nested in its own `node_modules`) are
+   * still left out. The package is the path through the last `node_modules/<name>` (or `node_modules/@scope/name`)
+   * in it, read from the path alone with no file system. A module not under `node_modules` changes nothing: the rule
+   * already keeps its spans. Unset by default.
+   */
+  readonly appModule?: string | undefined;
+}
+/**
+ * A failure as a document: what the default report prints, and a building block for a custom one.
+ *
+ * @remarks
+ * 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`: by default only the program's own spans, the kit's and Effect's left out (`spans`). 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.
+ * Building it never throws: an error whose `_tag`, `message`, `stack`, `cause` or `issue` getter throws is drawn without
+ * that part (an unreadable `stack` as `no stack`, an unreadable `cause` ending the chain there). Render it with `Render.context` and `Render.plain`, `ansi`, `markdown` or `githubLog`, or `Doc.print` it.
+ *
+ * @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;
+}
+/**
+ * An output format a `--format` flag can offer: `auto` (the renderer the audience gets, as `Doc.print` picks it),
+ * one of the `Doc` renderers by name, or `json`, the command's data rather than its document.
+ *
+ * @public
+ */
+type CliFormatName = "auto" | "plain" | "ansi" | "markdown" | "githubLog" | "json";
+/**
+ * Options for {@link CliFormat.flag}.
+ *
+ * @typeParam F - the built-in formats offered under their own names
+ * @typeParam A - the caller's alias names, each standing for a built-in format
+ * @typeParam C - the caller's own formats, which the caller renders itself
+ *
+ * @public
+ */
+interface CliFormatFlagOptions<F extends CliFormatName, A extends Readonly<Record<string, CliFormatName>> = Record<never, CliFormatName>, C extends string = never> {
+  /**
+   * The format when the flag is not given, spelled as on the command line (an alias by its own name): `auto` when it
+   * is offered, otherwise the first one.
+   */
+  readonly default?: F | Extract<keyof A, string> | C | undefined;
+  /** The flag's name; `format` by default. */
+  readonly name?: string | undefined;
+  /** The flag's description in help; one naming the offered formats by default. */
+  readonly description?: string | undefined;
+  /**
+   * Names of the caller's own that stand for a built-in format: `{ human: "auto" }` offers `--format human`, whose
+   * value is `auto`. The target need not be offered under its own name, so `["json"]` with `{ human: "auto" }` offers
+   * exactly `json` and `human`. An alias may not reuse a built-in format's name or any other offered name.
+   */
+  readonly aliases?: A | undefined;
+  /**
+   * Formats the caller renders itself, such as `mermaid` or `dot`: offered under their own names and yielded as
+   * themselves. {@link CliFormat.print} takes none of them; branch on a custom value before printing. A custom name
+   * may not reuse a built-in format's name or any other offered name.
+   */
+  readonly custom?: ReadonlyArray<C> | undefined;
+}
+/**
+ * What {@link CliFormat.print} prints: the command's document and, for `json`, its data.
+ *
+ * @public
+ */
+interface CliFormatOutput {
+  /** The document, built only when a document format is chosen. */
+  readonly doc: () => Document;
+  /** The data `json` prints, built only when `json` is chosen. A `json` format with no `json` here is a defect. */
+  readonly json?: (() => unknown) | undefined;
+}
+/**
+ * Options for {@link CliFormat.print}.
+ *
+ * @public
+ */
+interface CliFormatPrintOptions {
+  /** The stream to write to; stdout by default. */
+  readonly stream?: "stdout" | "stderr" | undefined;
+  /** The JSON indent, in spaces; `2` by default, `0` for one line. */
+  readonly indent?: number | undefined;
+}
+/**
+ * A `--format` flag and the one print that honours it, so a command builds its report once as a `Doc` and its data
+ * once as a value, and never writes per-format output by hand.
+ *
+ * @remarks
+ * The flag is core's `Flag.ChoiceWithValue` with the kit's names, default and description; the print hands every
+ * document format to `Doc.print` and writes `json` itself.
+ *
+ * ```ts
+ * const format = CliFormat.flag(["auto", "markdown", "json"])
+ * const doctor = Command.make("doctor", { format }, ({ format }) =>
+ *   CliFormat.print(format, { doc: () => report(results), json: () => results }),
+ * )
+ * ```
+ *
+ * @public
+ */
+export declare class CliFormat {
+  private constructor();
+  /**
+   * A `--format` flag offering `formats`, and the caller's own `aliases` and `custom` formats.
+   *
+   * @remarks
+   * Its default is `options.default`, else `auto` when it is offered, else the first format. Any other value is a
+   * usage error from core's parser, naming the accepted ones. The value is the built-in format a name stands for
+   * (`human` under `{ human: "auto" }` is `auto`), or a custom name as itself, so the value of a flag with no custom
+   * formats goes straight to {@link CliFormat.print}.
+   *
+   * Two offered names that clash (an alias or custom name reusing a built-in name, or any name offered twice) and a
+   * default that is not offered are programming mistakes: the call throws. A CLI that still accepts a `--json` of its
+   * own declares and resolves that flag itself; {@link CliFormat.printJson} prints the JSON the same way.
+   *
+   * ```ts
+   * // okfit's contract: --format human|json, and a graph command that also draws mermaid and dot
+   * const format = CliFormat.flag(["json"], { aliases: { human: "auto" }, default: "human" })
+   * const graph = CliFormat.flag(["json"], { custom: ["mermaid", "dot"], default: "mermaid" })
+   * ```
+   *
+   * @param formats - the built-in formats the command offers under their own names, at least one
+   * @param options - the default, the flag's name and description, aliases and custom formats
+   */
+  static readonly flag: <const F extends CliFormatName, const A extends Readonly<Record<string, CliFormatName>> = Record<never, CliFormatName>, const C extends string = never>(formats: readonly [F, ...ReadonlyArray<F>], options?: CliFormatFlagOptions<F, A, C>) => Flag.Flag<F | A[keyof A] | C>;
+  /**
+   * Print a command's output in `format`.
+   *
+   * @remarks
+   * `json` writes `output.json()` exactly as {@link CliFormat.printJson} writes a value, which it delegates to. Every
+   * other format prints `output.doc()` with `Doc.print`, which renders it as `auto` or the named renderer would.
+   *
+   * @param format - the chosen format, usually the value of {@link CliFormat.flag}
+   * @param output - the document and the data
+   * @param options - the stream and the JSON indent
+   */
+  static readonly print: (format: CliFormatName, output: CliFormatOutput, options?: CliFormatPrintOptions) => Effect.Effect<void, never, CliTheme | TerminalEnv | Audience | CliLinks>;
+  /**
+   * Print `value` as JSON, the way {@link CliFormat.print} prints the `json` format, for a CLI that keeps a JSON flag
+   * of its own.
+   *
+   * @remarks
+   * One `Console.log` (or `Console.error` for stderr), indented by `indent`: one document, never one line per item.
+   * Under GitHub Actions a `##[` inside it is written as the JSON escape `#\u0023[`, which decodes to the same
+   * text, so the runner cannot read it as a command. A value JSON cannot hold (a cycle, a bigint, `undefined`) is a
+   * defect. It needs no theme, terminal or audience: whether this is GitHub Actions is read from `CurrentRuntimeEnv`
+   * when the environment has it, and is "no" otherwise.
+   *
+   * ```ts
+   * const status = Command.make("status", { json: Flag.Boolean("json").pipe(Flag.withDefault(false)) }, ({ json }) =>
+   *   json ? CliFormat.printJson(results) : Doc.print(report(results)),
+   * )
+   * ```
+   *
+   * @param value - the data to print
+   * @param options - the stream and the JSON indent
+   */
+  static readonly printJson: (value: unknown, options?: CliFormatPrintOptions) => Effect.Effect<void>;
+}
+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`.
+ *
+ * @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`.
+ *
+ * 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.
+ *
+ * Both layers also hold core's `TerminalCapabilities.canPrompt` at `true`,
+ * keeping its `canColor` and `canAnimate` as they find them. Core skips a
+ * `Flag.withFallbackPrompt` or `Argument.withFallbackPrompt` fallback entirely
+ * when `canPrompt` is `false`, and decides that from the process's own
+ * terminal, so a kit fallback (`CliPrompt.fallback`, `CliUi.fallback`) would
+ * never be called in a piped run and its `otherwise` would be lost. With the
+ * gate held open, this reference makes the prompt decision instead: the kit's
+ * fallbacks answer without a person when it is `false`, and
+ * `CliPrompt.gateTerminal` quits any other prompt at once. A
+ * `TerminalCapabilities` with `canPrompt: false` provided inside the program,
+ * under these layers, bypasses the kit's fallbacks again: the parameter fails
+ * as missing even when an `otherwise` is given.
+ *
+ * @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" }))`.
+   *
+   * It also holds core's `TerminalCapabilities.canPrompt` at `true`; see {@link CliInteractive}.
+   *
+   * 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. It holds core's `canPrompt` open too, as {@link CliInteractive.layer} does.
+   *
+   * @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>;
+}
+/**
+ * Options for {@link CliMessage.status}.
+ *
+ * @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.
+ *
+ * @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.
+ *
+ * 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 glyph
+ * comes from the vocabulary, sanitised too (`Status.glyph`), so a glyph built from data cannot inject an escape either.
+ *
+ * @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>;
+}
+/**
+ * Which missing parameter a fallback stands in for, so a non-interactive run can fail with core's own error.
+ *
+ * @public
+ */
+type CliPromptTarget = {
+  readonly flag: string;
+} | {
+  readonly argument: string;
+};
+/**
+ * Options for {@link CliPrompt.fallback}.
+ *
+ * @public
+ */
+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();
+  /**
+   * A fallback for `Flag.withFallbackPrompt` or `Argument.withFallbackPrompt` that only prompts when the run is
+   * interactive.
+   *
+   * @remarks
+   * 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.
+   *
+   * Core runs `Prompt.run` on the answered prompt it is handed, and an answered prompt never reads the terminal's
+   * input (core acquires it only when a prompt needs a key), so piped stdin is left untouched without any gate.
+   * `CliPrompt.gateTerminal`, which `CliEnv.layer` installs, covers the prompts this function does not wrap.
+   *
+   * Core calls a fallback only when its `TerminalCapabilities.canPrompt` is `true`, and its own default decides that
+   * from the process's terminal, so in a piped run it would fail the parameter as missing without calling this
+   * function and `otherwise` would be lost. `CliInteractive.layer` and `CliInteractive.layerTest` (and so
+   * `CliEnv.layer`) hold `canPrompt` at `true` for that reason: the decision is `CliInteractive`'s, made here. A
+   * `TerminalCapabilities` with `canPrompt: false` provided inside the program bypasses this fallback again, and a
+   * program that sets `CliInteractive` with neither layer keeps core's own gate.
+   *
+   * @param prompt - the prompt to show
+   * @param options - the parameter it stands in for, and the non-interactive default
+   */
+  static readonly fallback: <A>(prompt: Prompt.Prompt<A>, options: CliPromptFallbackOptions<A>) => Param.FallbackPrompt<A>;
+  /**
+   * Gates core's `Terminal` on `CliInteractive`, so a run that is not interactive never touches the real one.
+   *
+   * @remarks
+   * A prompt that needs a key reads the terminal's input, and the real Node terminal then attaches a readline to
+   * stdin, which drops piped input and puts a TTY stdin into raw mode. Core's `withFallbackPrompt`, a `Prompt.run`
+   * in a handler and the command wizard all do so whether or not anyone is there to answer. Not interactive, this
+   * terminal's input is an already-ended queue, its `readLine` fails as quit and its `display` writes nothing, so
+   * any such prompt is quit at once and the real terminal is never read. Its `columns`, `rows` and `size` always come
+   * from the real one, so layout keeps working. Interactive, every call passes through to the real terminal.
+   *
+   * 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 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>;
+}
+/**
+ * What `render` is told about a failure beyond the squashed error.
+ *
+ * @public
+ */
+interface FailureDetails {
+  /** The whole cause the program failed with, before squashing. */
+  readonly cause: Cause.Cause<unknown>;
+  /**
+   * `true` when the cause carries no typed failure, so `error` is a defect:
+   * a `die`, a thrown exception, a bug. `false` when `error` is a typed
+   * failure from the error channel.
+   */
+  readonly isDefect: boolean;
+  /**
+   * `true` when the squashed `error` is the kit's {@link Cancelled}: the person quit a prompt or screen (Esc, Ctrl-C).
+   * It is not a bug and there is nothing to report, whichever channel it arrived through.
+   *
+   * @remarks
+   * A cancel from `CliPrompt.fallback` is a defect (`isDefect` is `true`) and one from `CliUi.run` is a typed failure
+   * (`isDefect` is `false`), so a `render` that gives a defect the "please report this" treatment must test this flag
+   * first, or Esc prints an issue-report request. `isDefect` keeps its plain meaning, the absence of a typed failure,
+   * and the exit code is unchanged (`130` for the `interrupt` reason). `defaultLines` and `lines()` already draw it as
+   * its one fixed line.
+   */
+  readonly isCancelled: boolean;
+  /**
+   * `true` when the squashed `error` is the kit's {@link NotInteractive}: the program asked for a prompt or a screen in
+   * a run that cannot show one (a pipe, an agent, a CI). It is a usage problem, not a bug, whichever channel it
+   * arrived through; `isDefect` is as for {@link FailureDetails.isCancelled}.
+   */
+  readonly isNotInteractive: 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))
+   * ```
+   *
+   * `spans` chooses the `in:` trail for these lines alone, as `CliFailureOptions.spans` does (`app`, `all` or
+   * `off`); without it the run's own setting (`env.spans`, `app` by default) applies.
+   *
+   * @param options - `status: false` leaves off the leading status; `spans` chooses the span trail
+   */
+  readonly lines: (options?: {
+    readonly status?: boolean | undefined;
+    readonly spans?: "app" | "all" | "off" | undefined;
+  }) => ReadonlyArray<string>;
+  /**
+   * The exit code this failure exits with: the error's own `Runtime.errorExitCode` when it carries one, else its
+   * entry in `exitCodes` (a typed failure only), else `exitCode`, else `1`.
+   *
+   * @remarks
+   * The code is decided before `render` is called, so a render can print it. A hook that parses a fixed stderr shape
+   * builds it here, reading the tag off `error` itself:
+   *
+   * ```ts
+   * const render = (error: unknown, details: FailureDetails) => {
+   *   const tag = Predicate.hasProperty(error, "_tag") && Predicate.isString(error._tag) ? error._tag : "Defect";
+   *   return `${details.exitCode} ${tag}: ${Fmt.sanitize(Fmt.describe(error))}`;
+   * };
+   * ```
+   */
+  readonly exitCode: number;
+}
+/**
+ * How a failure is turned into output and an exit code.
+ *
+ * @public
+ */
+interface ReportFailuresOptions {
+  /**
+   * 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
+   * followed by the rendered issue lines, say.
+   *
+   * `error` is the squashed cause: the first typed failure when there is
+   * one, otherwise the first defect. `details` says which it is, so a typed
+   * 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;
+  /**
+   * The exit code to use when the error does not carry one.
+   *
+   * @remarks
+   * An error carrying `Runtime.errorExitCode` keeps its own; this is only the
+   * fallback, and it defaults to `1`. Pass an integer in `0..255`, the range a
+   * POSIX exit status can carry — `256` wraps to `0` and passes a failed run.
+   */
+  readonly exitCode?: number | undefined;
+  /**
+   * Exit codes by tag: a typed failure whose `_tag` is a key here exits with that code.
+   *
+   * @remarks
+   * Checked after the error's own `Runtime.errorExitCode` (an error that chose its code keeps it) and before
+   * `exitCode`, which stays the fallback for every other failure, defects included. Only a typed failure is looked
+   * up: a defect that happens to carry a `_tag` exits with `exitCode`. A usage error (`usageExitCode`), a cancel
+   * (`130`) and a non-interactive prompt (`64`) carry their own codes and are not looked up either.
+   *
+   * Each code must be an integer in `1..255`: `0` would pass a failed run, and `256` wraps to `0`. Anything else
+   * throws a `RangeError` when the options are passed, since it is a wiring mistake, not a runtime condition.
+   *
+   * ```ts
+   * CliRuntime.main(program, { platform, exitCodes: { DataStoreError: 3, SidecarTimeoutError: 2 }, exitCode: 5 })
+   * ```
+   */
+  readonly exitCodes?: Readonly<Record<string, number>> | undefined;
+  /**
+   * The exit code for a usage error: a `ShowHelp` carrying parse errors, or a
+   * `CliError.UserError` `Command.runWith` already printed.
+   *
+   * @remarks
+   * Defaults to `64` (BSD `EX_USAGE`); pass an integer in `0..255`. A
+   * `ShowHelp` with no errors — a bare root invocation, or `--help` — always
+   * exits `0`. A `UserError` that carries its own `Runtime.errorExitCode` —
+   * one marked with `CliRuntime.reported(error, 3)` — keeps that code instead.
+   *
+   * Keep `Command.runWith`'s default `renderErrors`: with `renderErrors: false`
+   * runWith prints no parse errors and `reportFailures` never renders a
+   * `ShowHelp`, so a parse error would exit with this code having printed
+   * nothing on stderr.
+   */
+  readonly usageExitCode?: number | undefined;
+}
+/**
+ * Options for `CliRuntime.main`.
+ *
+ * @public
+ */
+interface MainOptions<RP, EP> extends ReportFailuresOptions {
+  /**
+   * The platform layer, usually `NodeServices.layer` or an app platform built
+   * 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()`, 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 follows its own terminal check, read from core's `Stdio`, so with stderr redirected and stdout
+   * a terminal the failure report goes into the file unpainted. `env.stderrIsTerminal` replaces that check for a
+   * host whose `Stdio` cannot say; a bin on the platform `Stdio` passes nothing.
+   */
+  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
+   * errors.
+   *
+   * @remarks
+   * `"stderr"` keeps stdout clean for a caller that parses it, such as a
+   * hook piping JSON into `jq`: an unknown flag, a bad value or an unknown
+   * subcommand then writes nothing to stdout. An explicit `--help` and a
+   * bare invocation of a command group still print help on stdout: neither
+   * is an error.
+   *
+   * `main` routes through core's `CliOutput.Presenter`, so the help and
+   * errors are rendered by whichever `CliOutput` Formatter is in effect
+   * where `Command.runWith` runs, one provided inside `program` included,
+   * and written to whichever `Console` is in effect there. To change the
+   * Formatter `main` installs, pass `env.formatter` (for example
+   * `formatVersion`); a Formatter the platform provides is shadowed by
+   * `main`'s, so pass it through `env.formatter` as well.
+   *
+   * The installed Formatter paints by stdout's terminal check. When `env` is set and stderr's colour decision
+   * differs from stdout's, a usage error's help is rendered with `formatHelpDoc`, `formatError` and `formatErrors` rebuilt from
+   * core's default formatter under stderr's decision (and `env.helpFlags`), so those methods follow stderr
+   * unless given through `env.formatter`, which always wins. Every other method is left as installed.
+   *
+   * Two cases keep help on stdout even under `"stderr"`. A `CliOutput`
+   * Presenter provided inside `program` replaces the routing. And with
+   * `Command.runWith`'s `renderErrors: false` core presents the help as
+   * plain help, with no errors, so it is not a usage error's.
+   */
+  readonly helpOnUsageError?: "stdout" | "stderr" | undefined;
+  /**
+   * The carrier package the bin was installed through, when a carrier launched it: `null` (or `undefined`) for a
+   * direct install.
+   *
+   * @remarks
+   * Given (even as `null`), `main` provides `@effected/kit`'s `CurrentDistribution` around the program, as
+   * `Option.some` of the carrier or `Option.none()`, so a program and the engine it calls read the same value. With a
+   * carrier, `--version` ends with its `via <name> <version>` suffix (`distributionSuffix`), appended to whatever
+   * `formatVersion` is in effect, the coloured default or `env.formatter`'s: do not also append it in
+   * `env.formatter`.
+   *
+   * Core's default `formatVersion` prints `<name> v<version>`. A program moving off a hand-rolled `--version` that
+   * printed another shape (no `v`, say) keeps it by passing that shape as `env.formatter`'s `formatVersion`; the
+   * suffix is appended to it either way.
+   *
+   * ```ts
+   * CliRuntime.main(CliAudience.run(root, { version }), { platform, env, distribution: options.distribution ?? null })
+   * ```
+   */
+  readonly distribution?: Distribution | null | undefined;
+}
+/**
+ * Report a CLI program's failures through the program's own logger.
+ *
+ * @remarks
+ * ## 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 —
+ * `makeRunMain` composes its reporting `tapCause` around the already-provided
+ * effect — so a program that carefully installs {@link CliLogger} still prints
+ * its failures in the structured format that logger exists to replace, and
+ * prints them on **stdout**, the one stream errors must not use.
+ *
+ * Nothing about the call site suggests this. The program looks correct, the
+ * logger is installed, every success path is right, and only a failure reveals
+ * it.
+ *
+ * ## Why a combinator, and not a `runMain`
+ *
+ * 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. 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.
+ *
+ * ## What it does with the failure
+ *
+ * Renders it through the ambient logger, then **re-fails with a marked error**
+ * so the runtime still sees a failure — the exit code is the runtime's to set,
+ * and swallowing the failure would make a broken run exit `0`.
+ *
+ * The marks are core's own, and they are what make this work without a platform
+ * import:
+ *
+ * - `Runtime.errorExitCode` — `defaultTeardown` takes the squashed error's
+ *   value as the process exit code. An error that already carries one **keeps
+ *   it**: that was a deliberate choice by whatever raised it, and flattening
+ *   every failure to a single code would discard it.
+ * - `Runtime.errorReported` — set to `false`, which suppresses the runtime's own
+ *   duplicate report. **The polarity is inverted relative to the name**: the
+ *   marker means "should this be reported", so the intuitive
+ *   `errorReported: true` — "I have reported it, stay quiet" — produces exactly
+ *   the double report it was meant to prevent.
+ *
+ * An **interrupt is left alone**: it is not a failure to report, and the
+ * default teardown already maps an interrupt-only cause to `130`.
+ *
+ * A `CliError.ShowHelp` is never rendered: `Command.runWith` already printed
+ * the help text (and any parse errors) before re-failing with it, so
+ * rendering it again would print nothing but a stray "Help requested" line.
+ * A `ShowHelp` carrying errors is remapped to `usageExitCode` (default `64`,
+ * BSD `EX_USAGE`); a bare `--help` or root invocation — `errors` empty —
+ * keeps exit `0`. A `CliError.UserError` whose `Runtime.errorReported` mark
+ * is `false` is likewise skipped: that is how `Command.runWith` leaves one it
+ * already rendered through its `CliOutput` formatter. It exits with its own
+ * `Runtime.errorExitCode` when it carries one, otherwise `usageExitCode`;
+ * under runWith's `renderErrors: false` the mark stays set, and it renders
+ * here like any other failure. A handler failure carrying a
+ * `CliError.userMessage` is skipped the same way, since `Command.runWith`
+ * renders it and sets the mark to `false`; it keeps the exit code a
+ * handler failure gets (`exitCodes` by tag, then `exitCode`). Every other
+ * error renders even when it already carries the reported mark — a gate
+ * failure marked with `CliRuntime.reported` still prints its line. The
+ * private `ExitRequested` sentinel `CliRuntime.main`
+ * raises is likewise never rendered; it only carries the exit code a
+ * successful program recorded through `CliExit`.
+ *
+ * @example
+ * ```ts
+ * import { CliRuntime } from "@effected/cli-kit"
+ * 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();
+  /**
+   * 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>;
+  /**
+   * Assemble a CLI program in the one order that reports every failure well.
+   *
+   * @remarks
+   * - `CliExit` is provided fresh, and a non-zero code after success becomes a
+   *   marked failure the teardown honours.
+   * - The platform layer is provided **inside** failure reporting, so a
+   *   layer-build failure (`HOME` unset, say) renders as one line with the
+   *   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.
+   *
+   * @example
+   * ```ts
+   * import { CliRuntime } from "@effected/cli-kit"
+   * import { NodeRuntime, NodeServices } from "@effect/platform-node"
+   * import { Command } from "effect/cli"
+   *
+   * NodeRuntime.runMain(
+   *   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 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.
+   *
+   * @remarks
+   * Exported because a program that reports a failure itself — a validation
+   * command that prints its own diagnostics, say — needs the same two marks
+   * and should not have to rediscover the inverted polarity.
+   *
+   * Under `CliRuntime.main` or {@link CliRuntime.reportFailures}, do NOT
+   * print the failure yourself before failing with it: `reportFailures`
+   * renders every error except a `ShowHelp`, a `CliError.UserError` whose
+   * reported mark is `false`, and any error carrying a string
+   * `[CliError.userMessage]` whose reported mark is `false`, so it would
+   * print twice. Fail with the marked
+   * error and put any multi-line rendering in the `render` option instead. The
+   * mark matters for a program run WITHOUT `reportFailures`, where it keeps the
+   * runtime from reporting a failure the program already printed.
+   *
+   * A `CliError.UserError` marked with `reported` is treated as already
+   * printed and is not rendered — use a different error type if the program
+   * has not printed it. `reportFailures` cannot tell a `UserError` that
+   * `Command.runWith` printed from one marked here: both carry the same `false`
+   * mark. It does keep the code you pass: `reported(userError, 3)` exits `3`,
+   * not `usageExitCode`.
+   *
+   * The same holds for an error carrying a string `[CliError.userMessage]`:
+   * `Command.runWith` prints such a handler failure and leaves the same
+   * `false` mark, so one marked here is treated as already printed and is not
+   * rendered. Mark an error without the annotation, or leave it unmarked, if
+   * the program has not printed it. It keeps the code you pass.
+   *
+   * The marks are added in place, so a typed error comes back as its own
+   * type: the `E` overload returns the very instance it was given, and a
+   * program failing with it keeps `catchTags` narrowing downstream without a
+   * cast. Any other value takes the `unknown` fallback and is wrapped in a
+   * plain `Error`.
+   *
+   * The `E extends Error` constraint is structural, not nominal — TypeScript
+   * cannot express "is really an `Error`", so the guarantee holds only when
+   * the argument passes `instanceof Error` at runtime. A value that merely
+   * satisfies `Error`'s shape (an object `implements Error`, or an error
+   * revived from JSON) still takes the wrapping branch and comes back as a
+   * fresh, stripped `Error` typed as `E`.
+   */
+  static reported<E extends Error>(error: E, exitCode?: number): E;
+  static reported(error: unknown, exitCode?: number): Error;
+}
+/**
+ * What {@link ConfigIssueRenderer.render} reads: anything that may carry an `issue` tree.
+ *
+ * @remarks
+ * A `@effected/config-file` `ConfigValidationError` is assignable to it, as is any
+ * other value with an optional `issue` property.
+ *
+ * @public
+ */
+interface ConfigIssueSource {
+  readonly issue?: unknown;
+}
+/**
+ * Turns a `@effected/config-file` `ConfigValidationError` into one line per rejected value.
+ *
+ * @remarks
+ * `ConfigValidationError` carries the structured `issue` tree rather than a
+ * 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.
+ *
+ * The parameter is {@link ConfigIssueSource}, a structural type, so this module
+ * names nothing from `@effected/config-file` and the package is not a peer. A
+ * real `ConfigValidationError` is assignable to it.
+ *
+ * @example
+ * ```ts
+ * import { ConfigIssueRenderer } from "@effected/cli-kit"
+ * import { Effect } from "effect"
+ *
+ * const load = configFile.load.pipe(
+ *   Effect.catchTag("ConfigValidationError", (error) =>
+ *     Effect.gen(function* () {
+ *       yield* Effect.logError(String(error))
+ *       for (const line of ConfigIssueRenderer.render(error)) yield* Effect.logError(`  ${line}`)
+ *     }),
+ *   ),
+ * )
+ * ```
+ *
+ * @public
+ */
+export declare class ConfigIssueRenderer {
+  private constructor();
+  /**
+   * One line per rejected value.
+   *
+   * @remarks
+   * Takes the **error**, not its `issue`, because that is what a `catchTag`
+   * 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
+   * shape.
+   *
+   * An unknown key the schema has a near match for at the same path ends in a
+   * hint, `unknown key at theme.colour (did you mean "color"?)`, drawn from the
+   * keys the struct declares there (every branch's, under a union) with
+   * {@link Fmt.suggest}'s threshold. A key with no near match is drawn exactly
+   * as {@link SchemaIssueRenderer} draws it.
+   *
+   * 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: ConfigIssueSource) => ReadonlyArray<string>;
+}
+/**
+ * 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;
+}
+/**
+ * Options for {@link Fmt.pad}.
+ *
+ * @public
+ */
+interface PadOptions {
+  /**
+   * Where the text sits in the padded field: `left` (the default) fills on the right, `right` fills on the left, and
+   * `center` splits the fill, the odd column going on the right.
+   */
+  readonly align?: "left" | "right" | "center" | undefined;
+  /** The fill, one column wide; a space by default. Anything that is not exactly one column wide is a space. */
+  readonly fill?: string | undefined;
+}
+/**
+ * Options for {@link Fmt.suggest}.
+ *
+ * @public
+ */
+interface SuggestOptions {
+  /** The most edits a suggestion may be away from the input; `2` by default, as `effect/cli` uses. */
+  readonly maxDistance?: number | 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 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. The format is bespoke: core's `Duration.format` renders differently.
+   *
+   * The input is anything `Duration.Input` admits. A plain number is milliseconds and is used as given, never
+   * converted through a `Duration`, which rounds a fractional millisecond to whole nanoseconds and would move a value
+   * such as `999.4999999` across the rounding boundary. A `bigint` is nanoseconds, as in core. A negative, infinite
+   * or invalid input (a string `Duration.Input` cannot parse) is `0ms`: a formatter in a render path never throws.
+   *
+   * @param input - the duration; a number is milliseconds
+   */
+  static readonly duration: (input: Duration.Input) => 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;
+  /**
+   * Pad `text` to `width` terminal columns, measured as {@link Fmt.width} measures: a wide character counts two and
+   * an escape sequence none, so coloured text pads to the same column as plain text.
+   *
+   * @remarks
+   * Text already `width` columns or wider is returned unchanged: compose with {@link Fmt.truncate} to cut it. A
+   * `width` that is not a finite number pads nothing. Never throws.
+   *
+   * @param text - the text to pad
+   * @param width - the columns the result should take
+   * @param options - the alignment and the fill
+   */
+  static readonly pad: (text: string, width: number, options?: PadOptions) => string;
+  /**
+   * `text` without its escape sequences: CSI (colour, cursor moves, erases), OSC (titles, OSC 8 hyperlinks) ending in
+   * BEL or ST, the DCS, SOS, PM and APC strings, and every other escape, the nF sequences (`ESC ( B`) and the
+   * two-byte ones (`ESC 7`, `ESC 8`, `ESC =`, `ESC c`).
+   *
+   * @remarks
+   * The same strip {@link Fmt.width} and {@link Fmt.sanitize} start from. Only complete sequences go: a lone ESC, or
+   * any other control character, is kept, and so is an ESC in front of a lowercase letter other than `c`, which a
+   * stray ESC before a word would otherwise cost the word its first letter. An unterminated CSI or OSC keeps its `[`
+   * or `]`. Use {@link Fmt.sanitize} for text that will be laid out and printed.
+   *
+   * @param text - the text
+   */
+  static readonly stripAnsi: (text: string) => string;
+  /**
+   * Whether `text` is nothing but escape sequences, as {@link Fmt.stripAnsi} reads them: a cursor hide or show, a
+   * clear-screen, an erase-scrollback. Empty text is not escape-only, and neither is a bare control character
+   * (`\r`, BEL), which is not an escape sequence.
+   *
+   * @param text - the text
+   */
+  static readonly isEscapeOnly: (text: string) => boolean;
+  /**
+   * Integers as compact ranges: `[1, 2, 3, 5, 10, 11]` is `"1-3,5,10-11"`, a run of consecutive numbers written
+   * `start-end` and the rest one by one, joined with commas.
+   *
+   * @remarks
+   * The input is sorted and its duplicates dropped first, so order does not matter. Anything that is not a finite
+   * integer is left out, and no input is `""`. Never throws.
+   *
+   * @param numbers - the integers, such as line numbers
+   */
+  static readonly ranges: (numbers: Iterable<number>) => string;
+  /**
+   * Any value as text, without ever throwing.
+   *
+   * @remarks
+   * A string is itself; a number, boolean, bigint or symbol is `String(value)`; `undefined` and `null` are
+   * `"undefined"` and `"null"`. A value with a string `message` (an `Error`, one from another realm, a plain
+   * `{ message }`) is that message. Anything else is its JSON, or `String(value)` when it has none (a cycle, a
+   * function), or `"[unprintable value]"` when that throws too. A getter that throws is a value with no message.
+   *
+   * The text is not sanitised: pass it through {@link Fmt.sanitize} before printing data you do not control. For
+   * the messages along an error's `cause` chain, use {@link Fmt.causeMessage}; for the two combined, use
+   * {@link Fmt.errorText}.
+   *
+   * It is `@effected/kit`'s `ErrorText.describe`, the same function, so a front end that cannot depend on this
+   * package (an MCP server) describes a value with the same words.
+   *
+   * @param value - the value
+   */
+  static readonly describe: (value: unknown) => string;
+  /**
+   * Every distinct non-empty message along a value's `cause` chain, nearest first and joined with `: `, or
+   * `undefined` when nothing along it has one.
+   *
+   * @remarks
+   * The kit's one guarded cause-message read, the one its own errors render a preserved cause with. A node's message
+   * is a thrown string or a non-empty string `message` property, read without `instanceof Error`, so an error from
+   * another realm or a plain `{ message }` object counts. A deeper message the joined text already contains is not
+   * repeated, and one that contains the joined text replaces it, so a `SqlError` wrapping SQLite's own text reads
+   * `Failed to execute statement: SQLITE_BUSY: database is locked`. It is the whole chain, not the innermost
+   * message alone. The walk stops after eight nodes, so a cyclic chain terminates.
+   *
+   * Never throws: a `message` getter that throws leaves that node without text, and a `cause` getter that throws ends
+   * the walk with the text found so far, `undefined` when there is none, so a caller's own fallback
+   * (`?? Fmt.describe(value)`, which {@link Fmt.errorText} spells once) applies.
+   *
+   * It is `@effected/kit`'s `ErrorText.causeMessage`, the same function.
+   *
+   * @param value - the error, or whatever was thrown
+   */
+  static readonly causeMessage: (value: unknown) => string | undefined;
+  /**
+   * The text of an unknown failure: {@link Fmt.causeMessage} when the chain carries a message, otherwise
+   * {@link Fmt.describe}.
+   *
+   * @remarks
+   * Exactly `Fmt.causeMessage(value) ?? Fmt.describe(value)`, the fallback an I/O site turning a caught value into
+   * text would otherwise spell out by hand at every call. An error whose message is empty and whose chain carries none
+   * is `""`, as `describe` reads it. Never throws, and not sanitised: pass it through {@link Fmt.sanitize} before
+   * printing data you do not control. It is `@effected/kit`'s `ErrorText.of`, the same function.
+   *
+   * @param value - the error, or whatever was thrown
+   */
+  static readonly errorText: (value: unknown) => string;
+  /**
+   * The candidates nearest to `input`, for a "did you mean" hint: those at the smallest edit distance found, up to
+   * `maxDistance` edits (two by default), in the order given, each once. No candidate that close is `[]`.
+   *
+   * @remarks
+   * The distance is Levenshtein's (one insertion, deletion or substitution per edit), over UTF-16 code units and
+   * case-sensitive, with the same two-edit threshold and the same ties-all-kept rule `effect/cli` uses for an unknown
+   * subcommand or flag, so a program's own suggestions agree with the parser's. A candidate equal to `input` is at
+   * distance zero and is the only one returned.
+   *
+   * The cost is linear in the candidates' total length: a candidate whose length differs from `input`'s by more than
+   * `maxDistance` is skipped unmeasured, and only the band of the edit matrix within `maxDistance` of its diagonal is
+   * measured, so a long typed value cannot make it quadratic. A `maxDistance` that is not a non-negative integer is a programming mistake and
+   * throws a `RangeError`.
+   *
+   * ```ts
+   * Fmt.suggest("stauts", ["status", "stack", "build"]) // => ["status"]
+   * ```
+   *
+   * @param input - what was typed: an unknown key, a profile name, a phase name
+   * @param candidates - the names it could have meant
+   * @param options - the most edits a suggestion may be away
+   */
+  static readonly suggest: (input: string, candidates: Iterable<string>, options?: SuggestOptions) => ReadonlyArray<string>;
+}
+/**
+ * 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;
+}
+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;
+}
+/**
+ * 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 writing to a terminal `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), and gives no limit
+   * when the stream is not a terminal; 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 braille pattern blank (U+2800, one blank cell) in front of such a
+   * `::` line and before the `[` of 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;
+  /**
+   * How many GitHub Actions log groups are open around the output. Unset or `0`, none is: `Render.githubLog` then
+   * writes a top-level collapsible as a `::group::`. Above `0` it writes the collapsible as plain does, its title on
+   * a line and its body indented, because the runner does not nest groups and a second `::group::` would end the open
+   * one. The other renderers do not read it.
+   *
+   * @remarks
+   * `Render.context` reads it from the fiber-local keyed by `WorkflowCommand.groupDepthKey`
+   * (`@effected/github-commands`), the count `ActionLogger.group` in `@effected/github-actions` provides around a
+   * group's body, so a context built inside a group knows it. It is read when the context is built, not when a
+   * document is rendered: a context built outside a group and used inside one still says none is open, so build it
+   * where the document is printed, as `Doc.print` does.
+   */
+  readonly groupDepth?: number | 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;
+  /** See {@link RenderContext.groupDepth}; unset (no group open) by default. */
+  readonly groupDepth?: number | undefined;
+}
+/**
+ * Options for {@link Render.context}.
+ *
+ * @public
+ */
+interface RenderContextOptions {
+  /**
+   * The display columns to lay out at. By default a human writing to a terminal gets `TerminalEnv.width()`, the
+   * terminal's columns as stdout reports them even when the stream is `"stderr"`; a human whose stream is not a
+   * terminal (a pipe, a file), an agent and a CI get 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-kit"
+ *
+ * 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 whose stream is a terminal, and **unbounded**
+   *   (`Infinity`) for a human whose stream is not one (`tool | grep`, `tool > out.txt`), an agent or a CI, so nothing
+   *   a reader needs is truncated or wrapped for a terminal that is not there: a pipe has no width to honour;
+   * - `groupDepth` is the fiber's count of open Actions log groups (the fiber-local keyed by
+   *   `WorkflowCommand.groupDepthKey`, which `ActionLogger.group` provides), set when it is above `0`, so a
+   *   document printed inside a group opens no second one; see {@link RenderContext.groupDepth}.
+   * - `displayPath` is the option, else the run's own path display (`CliEnvOptions.displayPath`, which
+   *   `CliEnv.layer` sets), else the identity.
+   *
+   * @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, link base and
+   *   open group depth
+   */
+  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 blank marker, 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, though a `##[` in its message,
+   * title or file is. 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.
+   *
+   * A group already open around the output counts the same way. When the context's `groupDepth` is above `0`
+   * ({@link RenderContext.groupDepth}, which `Render.context` reads from the fiber-local `ActionLogger.group` in
+   * `@effected/github-actions` provides, by the key `WorkflowCommand.groupDepthKey`), a top-level collapsible keeps
+   * plain's rendering too, so a document printed inside an `ActionLogger.group` does not open a second group, which
+   * would end the first at the runner. The depth is the context's, read when the context was built. What no depth
+   * can fix is two fibers writing groups at once: the runner has one log stream, so concurrent sibling groups, this
+   * renderer's or `ActionLogger`'s, interleave in it. Render and print a document from the fiber that owns the
+   * stream, not from a fiber racing another group.
+   *
+   * 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 braille pattern blank (U+2800) in
+   * front, which the runner neither trims nor skips, and every `##[` gets one before the `[`. The text is
+   * otherwise unchanged. A
+   * group's title is a command's data, so its `%`, CR and LF are escaped and a `##[` in it is neutralized. 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;
+}
+/**
+ * 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`. 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.
+ *
+ * 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
+ * import { SchemaIssueRenderer } from "@effected/cli-kit"
+ * import { Effect, Schema } from "effect"
+ *
+ * const result = Schema.decodeUnknownEffect(MySchema)(input, {
+ *   onExcessProperty: "error",
+ *   errors: "all",
+ * })
+ *
+ * const reported = result.pipe(
+ *   Effect.catchTag("SchemaError", (error) =>
+ *     Effect.forEach(SchemaIssueRenderer.render(error.issue), (line) => Effect.logError(`  ${line}`)),
+ *   ),
+ * )
+ * ```
+ *
+ * @public
+ */
+export declare class SchemaIssueRenderer {
+  private constructor();
+  /**
+   * One line per rejected value, deepest path last.
+   *
+   * @param issue - a `SchemaIssue` tree, or any value
+   * @returns the lines, or empty when `issue` is not an issue tree
+   */
+  static readonly render: (issue: unknown) => ReadonlyArray<string>;
+}
+export type { AnnotationLevel, AnnotationOptions, AudienceFlagInput, Block, BlockOf, CliAudienceFlagsOptions, CliDocSource, CliEnvOptions, CliEnvServices, CliEnvTestOptions, CliEnvTestServices, CliExitShape, CliFailureOptions, CliFormatFlagOptions, CliFormatName, CliFormatOutput, CliFormatPrintOptions, CliHelpFlags, CliLinksLinkerOptions, CliLinksOptions, CliLinksShape, CliLogFile, CliLogFileOptions, CliLogOptions, CliLogStatusOptions, CliLoggerOptions, CliMessageOptions, CliPromptFallbackOptions, CliPromptTarget, CliThemeOptions, CliThemeShape, CliThemeTestOptions, Column, ConfigIssueSource, CoreStatusName, Counter, CountsOptions, CountsRow, CountsTableOptions, DocPrintOptions, Document, EditorLinks, FailureDetails, GithubAnnotationProperties, GlyphSelectOptions, GlyphSet, Inline, InlineInput, InlineOf, LinkOptions, LinkTarget, ListOptions, MainOptions, NamedColor, OverflowOptions, PadOptions, PercentOptions, RenderContext, RenderContextOfOptions, RenderContextOptions, ReportFailuresOptions, RequiresAudienceFlags, StatusDef, StatusRef, StreamTheme, Style, SuggestOptions, TableOptions, TokenName, TreeInput, TreeNode, TruncateOptions };
+//# sourceMappingURL=index.d.ts.map