@effected/cli 0.10.0 → 0.12.0

package/GithubAnnotation.js

@@ -0,0 +1,40 @@
+import { WorkflowCommand } from "@effected/github-commands";
+
+//#region src/GithubAnnotation.ts
+/**
+* GitHub Actions annotations, as workflow commands.
+*
+* @public
+*/
+var GithubAnnotation = class {
+	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 format = (annotation, message) => {
+		return WorkflowCommand.render(annotation.level, {
+			title: annotation.title,
+			file: annotation.file,
+			line: annotation.line,
+			endLine: annotation.endLine,
+			col: annotation.col,
+			endColumn: annotation.endColumn
+		}, message);
+	};
+};
+
+//#endregion
+export { GithubAnnotation };

package/Glyphs.js

@@ -0,0 +1,83 @@
+//#region src/Glyphs.ts
+/**
+* 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
+*/
+var Glyphs = class Glyphs {
+	constructor() {}
+	/** Unicode symbols. */
+	static unicode = Object.freeze({
+		kind: "unicode",
+		ellipsis: "…",
+		spinner: Object.freeze([
+			"⠋",
+			"⠙",
+			"⠹",
+			"⠸",
+			"⠼",
+			"⠴",
+			"⠦",
+			"⠧",
+			"⠇",
+			"⠏"
+		]),
+		bullet: "•",
+		arrow: "→",
+		pathSeparator: Object.freeze({
+			human: "›",
+			agent: " > "
+		}),
+		spinnerIntervalMs: 80,
+		tree: Object.freeze({
+			branch: "├─ ",
+			last: "└─ ",
+			pipe: "│  ",
+			blank: "   "
+		})
+	});
+	/**
+	* 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 select = (options) => {
+		const ascii = options?.ascii ?? "auto";
+		return ascii === true || ascii === "auto" && options?.term === "dumb" ? Glyphs.ascii : Glyphs.unicode;
+	};
+	/** ASCII-only symbols. */
+	static ascii = Object.freeze({
+		kind: "ascii",
+		ellipsis: "...",
+		spinner: Object.freeze([
+			"-",
+			"\\",
+			"|",
+			"/"
+		]),
+		bullet: "*",
+		arrow: "->",
+		pathSeparator: Object.freeze({
+			human: ">",
+			agent: " > "
+		}),
+		spinnerIntervalMs: 80,
+		tree: Object.freeze({
+			branch: "|-- ",
+			last: "\\-- ",
+			pipe: "|   ",
+			blank: "    "
+		})
+	});
+};
+
+//#endregion
+export { Glyphs };

package/NotInteractive.js

@@ -0,0 +1,42 @@
+import { Runtime, Schema } from "effect";
+
+//#region src/NotInteractive.ts
+/**
+* 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
+*/
+var NotInteractive = class extends Schema.TaggedError()("NotInteractive", {}) {
+	/**
+	* 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() {
+		return "not interactive: run in a terminal or pass the flag";
+	}
+	set message(_value) {}
+	/**
+	* 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]() {
+		return 64;
+	}
+};
+
+//#endregion
+export { NotInteractive };

package/README.md

@@ -5,12 +5,12 @@
 [![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
 [![TypeScript 7.0](https://img.shields.io/badge/TypeScript-7.0-3178c6.svg)](https://www.typescriptlang.org/)
 
-The boundary layer of a command-line program built on `effect/cli`: how output reaches a human, how a failure is reported, and how a schema issue becomes a sentence someone can act on. `CliLogger` renders log records as plain lines and routes diagnostics to stderr, reading the `Console` off the fiber so it needs no platform package and the stream split is actually testable. `CliRuntime.reportFailures` catches inside your program so a failure prints through *your* logger instead of Effect's default one on stdout, then re-fails with the exit code and the no-double-report mark; `CliRuntime.main` assembles a whole program — platform layer, a fresh `CliExit`, failure reporting, and the logger — in the one order that reports every failure well. `CliExit` lets a findings command (a linter that found problems, say) succeed with a non-zero exit code, with finalizers intact on any runtime. `CliColor` decides once, per the no-color.org rule, whether output carries ANSI colour, and hands core's own `CliOutput.Formatter` the same decision. `SchemaIssueRenderer` and `ConfigIssueRenderer` turn issue trees into `unknown key at groups.g.rulesetz`. The `./testing` subpath's `CliTest` spawns a built bin hermetically for a test that wants a real subprocess.
+The presentation boundary of a command-line program built on `effect/cli`: who the output is for, and how it reaches them. Plain log lines on the right stream. Colour, glyphs and links only where the terminal and the reader can use them. Documents rendered for a person, an agent or a CI log. Failures reported through your own logger with the right exit code. Prompts that know when there is nobody to ask. Interactive screens and live progress views drawn with Ink. `effect/cli` still owns argument parsing, flags, the command tree and help; this package adds no parser and no command model.
 
-> **Pre-release.** This package is part of the `@effected/*` kit, in pre-`1.0.0`
-> development against a single pinned Effect v4 prerelease. Packages graduate to
-> `1.0.0` once Effect `4.0.0` ships. To hold your own `effect` versions at
-> exactly the ones the kit is built and tested against, install
+> **Pre-`1.0.0`.** This package is part of the `@effected/*` kit, built on stable
+> Effect v4 (`effect` `^4.0.0`) and still in `0.x` development. Stable Effect
+> makes a kit `1.0.0` possible, not automatic. To keep your `effect` and
+> `@effect/*` versions on the line the kit is built and tested against, install
 > [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
 >
 > **Stability: unstable.** This package's API surface is not yet considered
@@ -21,181 +21,195 @@ The boundary layer of a command-line program built on `effect/cli`: how output r
 
 ## Why @effected/cli
 
-Everything here shares one property: **you only discover you needed it by shipping bad output to a person.** None of it fails a type-check, a test, or a review of the code in isolation.
+Everything here shares one property: **you only discover you needed it by shipping bad output to a person or a machine.** None of it fails a type-check, a test, or a review of the code in isolation.
 
-Effect's default logger emits `[00:33:56.619] INFO (#2): message`. That is correct for a service being scraped and wrong for a tool someone is watching — it turns a formatted table into noise — and nothing at the call site suggests it. A platform `runMain` then reports an unhandled failure through that *same* default logger, which sits outside the layers your program was provided, so a program that carefully installs a CLI logger still prints its failures in the format that logger exists to replace, on **stdout**, the one stream errors must not use. And a decode failure arrives as a structured tree when what a user needs is a sentence naming the key they got wrong; core does ship formatters for this, but they live on `SchemaIssue` rather than `SchemaError`, are named `makeFormatter*`, and are not referenced by `SchemaError.message` — two engineers searched for two rounds and concluded they did not exist.
+Effect's default logger emits `[00:33:56.619] INFO (#2): message`, which is right for a service and noise for a tool someone is watching. A platform `runMain` reports an unhandled failure through that same default logger, outside the layers your program was given, so it prints on **stdout**, the one stream errors must not use. Colour codes end up in an agent's context window. A prompt fires inside a pipe and hangs. A file name containing `::error::` becomes a workflow command in GitHub Actions. And a decode failure arrives as a structured tree when a user needs a sentence naming the key they got wrong.
 
-This package is **not a CLI framework**. `effect/cli` owns argument parsing, flags, the command tree and help, and this package must never grow a second one.
+This package makes those decisions once, at the edge of the program, from the environment it actually runs in.
 
 ## Install
 
 ```bash
-npm install @effected/cli effect
+npm install @effected/cli @effected/env @effected/glob @effected/walker effect
 ```
 
 ```bash
-pnpm add @effected/cli effect
+pnpm add @effected/cli @effected/env @effected/glob @effected/walker effect
 ```
 
-Requires Node.js >=24.11.0. `effect` v4 is a peer dependency.
+Requires Node.js >=24.11.0. `effect` v4, `@effected/env` (the audience and terminal services), and `@effected/walker` with its `@effected/glob` peer (the project root for editor links) are peer dependencies. The one runtime dependency is `@effected/github-commands`. The package never imports a platform package, so it runs unchanged on Node, Bun and Deno.
 
-All `@effected/*` packages are ESM-only: the exports maps publish only `import` conditions, so `require()` — including tools that resolve in CJS mode — fails with Node's `ERR_PACKAGE_PATH_NOT_EXPORTED` rather than loading a CJS build that does not exist. Import from an ES module.
+Optional peers:
 
-`@effected/config-file` is an **optional** peer, needed only for `ConfigIssueRenderer`. It lives in its own module and is imported as a type, so nothing at runtime reaches for it.
+- **`ink` and `react`**, plus **`@types/react`** for TypeScript, for the interactive screens and live views in `@effected/cli/ui`. The root never reaches them, and `./ui` loads neither until a screen first mounts. Without `@types/react`, a program compiled with `skipLibCheck` silently types every screen as `any`.
 
-## Quick start
-
-```ts
-import { CliLogger, CliRuntime } from "@effected/cli";
-import { NodeRuntime } from "@effect/platform-node";
-import { Console, Effect, Layer } from "effect";
+  ```bash
+  npm install ink react @types/react
+  ```
 
-declare const AppLive: Layer.Layer<never>;
+- **`@effected/config-file`**, only for `ConfigIssueRenderer`. It is imported as a type, so nothing at runtime reaches for it.
 
-const program = Effect.gen(function* () {
-  yield* Effect.logInfo("building 3 packages"); // a diagnostic, not the product
-  yield* Console.log("build.json contents");    // the program's actual output
-  yield* Effect.logError("nothing to build");
-});
-
-// Merged, not provided beneath: this way it also covers lines emitted during
-// layer construction, which is exactly where a startup failure prints.
-const MainLive = Layer.mergeAll(AppLive, CliLogger.layer());
+All `@effected/*` packages are ESM-only: the exports maps publish only `import` conditions, so `require()` fails with Node's `ERR_PACKAGE_PATH_NOT_EXPORTED`. Import from an ES module.
 
-NodeRuntime.runMain(program.pipe(CliRuntime.reportFailures(), Effect.provide(MainLive)));
-// stdout: build.json contents
-// stderr: building 3 packages
-// stderr: nothing to build
-// No timestamp, no level, no fiber id — and stdout carries only what Console.log wrote.
-```
+## Quick start
 
-Rendering a bad config into something actionable:
+One wiring serves every program: share the audience flags on the root command, run it through `CliAudience.run`, and hand that to `CliRuntime.main` with an `env`.
 
 ```ts
-import { CliRuntime, ConfigIssueRenderer } from "@effected/cli";
+import { CliAudience, CliExit, CliMessage, CliRuntime, Doc } from "@effected/cli";
+import { NodeRuntime, NodeServices } from "@effect/platform-node";
 import { Effect } from "effect";
+import { Command } from "effect/cli";
 
-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}`);
-
-      // Re-fail, or the handler SUCCEEDS and a CLI exits 0 on invalid config.
-      // `reported` carries the exit code and the mark that stops the runtime
-      // printing the same failure a second time.
-      return yield* Effect.fail(CliRuntime.reported(error));
-    }),
-  ),
+const sync = Command.make("sync", {}, () =>
+  Effect.gen(function* () {
+    yield* CliMessage.info("syncing 2 repositories");
+    yield* Doc.print([
+      Doc.table(
+        [{ header: "Repository" }, { header: "Files", align: "right" }],
+        [
+          ["acme/widgets", "12"],
+          ["acme/gadgets", "3"],
+        ],
+      ),
+    ]);
+    yield* CliMessage.warning("acme/gadgets has no default branch");
+    // A finding, not a crash: the handler succeeds and the run still exits 1.
+    yield* CliExit.set(1);
+  }),
+);
+
+const root = Command.make("tool").pipe(Command.withSharedFlags(CliAudience.flags()), Command.withSubcommands([sync]));
+
+NodeRuntime.runMain(
+  CliRuntime.main(CliAudience.run(root, { version: "1.0.0" }), {
+    platform: NodeServices.layer,
+    env: {
+      audienceEnvVar: "TOOL_AUDIENCE",
+      stderrIsTerminal: Effect.sync(() => process.stderr.isTTY === true),
+    },
+  }),
 );
 ```
 
 ```text
-ConfigValidationError: Config validation failed at "/home/me/.config/app/config.toml"
-  unknown key at variables.keep.KEEP_ME
-  Missing key at variables.keep.file
-  Missing key at variables.keep.value
-  Missing key at variables.keep.resolved
+$ tool sync
+ℹ syncing 2 repositories
+Repository    Files
+------------  -----
+acme/widgets     12
+acme/gadgets      3
+⚠ acme/gadgets has no default branch
+$ echo $?
+1
 ```
 
-Print-then-`reported` is for a program run **without** `CliRuntime.main` or `reportFailures`. Under either, do not print the failure yourself: `reportFailures` renders every error except a `ShowHelp`, a `CliError.UserError` whose reported mark is `false` (one `Command.runWith` already printed, or one you marked with `reported`) and the `CliExit` sentinel, so it would print twice. Fail with the error and put the multi-line rendering in the `render` option instead — see "Rendering a multi-line failure" in the [advanced guide](https://effected.spencerbeg.gs/cli/advanced#rendering-a-multi-line-failure).
+At a colour terminal the glyphs are painted and the header is bold. For an agent (`--agent`, `TOOL_AUDIENCE=agent`, or an agent detected from the environment), in a pipe, or under `NO_COLOR`, the same program writes no escape sequence of any kind. Under GitHub Actions, anything the runner could read as a workflow command is neutralized. A failure anywhere renders as a short report on stderr and exits non-zero.
 
-## Putting it together
+## Audiences
 
-A findings command — one whose non-zero exit reports a result rather than a
-crash — wires `CliRuntime.main`, `CliExit.set` and `CliColor.formatterLayer`
-around an ordinary `effect/cli` command:
+The audience is decided once per run: an audience flag (`--audience <human|agent|ci>`, `--human`, `--agent`, `--ci`), then the override variable you name, then an agent detected from the environment, then CI, else a human. It decides:
 
-```ts
-import { CliColor, CliExit, CliRuntime } from "@effected/cli";
-import { NodeRuntime, NodeServices } from "@effect/platform-node";
-import { Console, Effect, Layer } from "effect";
-import { Command, Flag } from "effect/cli";
+| | Human | Agent | CI |
+| --- | --- | --- | --- |
+| Colour | When the stream has it | Never, even with `FORCE_COLOR` | When the stream has it (messages) |
+| `Doc.print` | `ansi`: painted, OSC 8 links | `plain` | `githubLog` under GitHub Actions, else `plain` |
+| Width | The terminal's | Unbounded | Unbounded |
+| Diagnostics (`CliLog`) | Pretty lines | NDJSON | NDJSON |
+| Prompts and screens | When interactive | Never | Never |
 
-const findProblems = (strict: boolean): ReadonlyArray<string> =>
-  strict ? ["missing changeset", "unpinned dependency"] : ["missing changeset"];
+Colour follows Node's precedence, per stream: `FORCE_COLOR` decides first and beats `NO_COLOR` (`1`–`3` on, even in a pipe; `0` off). Otherwise there is no colour without a terminal. On a terminal, a non-empty `NO_COLOR`, `NODE_DISABLE_COLORS` or `TERM=dumb` turns it off. `TERM=dumb` also switches to ASCII glyphs and makes the run non-interactive.
 
-const check = Command.make("check", { strict: Flag.Boolean("strict").pipe(Flag.withDefault(false)) }, (config) =>
-  Effect.gen(function* () {
-    const problems = findProblems(config.strict);
-    for (const problem of problems) yield* Console.log(problem);
+## Output
 
-    // Findings, not a crash: the handler still SUCCEEDS. CliExit.set records
-    // the code CliRuntime.main turns into a real exit once the program ends.
-    if (problems.length > 0) yield* CliExit.set(1);
-  }),
-);
+- **`CliMessage`**: `success`, `info`, `warning`, `failure` and `status(vocab, name, text)`. One themed line each, through `Console` rather than the logger, so no log level silences them. Warnings and failures go to stderr.
+- **`Doc` and `Render`**: a document IR (headings, paragraphs, lists, tables, trees, counts, count tables, collapsibles, callouts, code blocks, diffs, GitHub annotations) and pure `plain`, `ansi`, `markdown` and `githubLog` renderers. `Doc.print` picks the renderer for the audience, and lays out at the terminal's width only when the stream is a terminal: piped output (`tool | grep`) never wraps. `Doc.line(content, { wrap: false })` keeps one line whole at any width, glyph and colour included. `Render.contextOf` renders outside Effect, for example markdown for a step summary.
+- **`CliTheme`, `Token`, `Status`, `Glyphs`**: semantic tokens (`success`, `failure`, `warning`, `info`, `error`, `muted`, `accent`, `emphasis`), an extendable status vocabulary with glyphs and ranks, and Unicode or ASCII glyph sets. Override tokens with `env.theme`.
+- **`CliLinks`**: file links that open in VS Code (`vscode://file/…`) or as `file://` URLs, as OSC 8 hyperlinks where the terminal renders them, never for an agent.
+- **`Fmt`**: `sanitize`, `width`, `truncate`, `duration`, `percent` and `plural`.
 
-// Satisfies Command.Environment (Command.run needs it) AND feeds Stdio to
-// CliColor.formatterLayer, so help text, parse errors and rendered output
-// never disagree about whether colour is on.
-const Platform = CliColor.formatterLayer().pipe(Layer.provideMerge(NodeServices.layer));
+Every string that enters a document or a message is sanitised: escape sequences and control characters are removed, so data cannot paint the terminal or plant a link.
 
-// CliRuntime.main provides a fresh CliExit, the platform layer inside failure
-// reporting, and the logger outermost — do NOT provide CliExit.layer here
-// yourself, or CliExit.set writes to a second, unread cell and `check`
-// silently exits 0.
-NodeRuntime.runMain(CliRuntime.main(Command.run(check, { version: "1.0.0" }), { platform: Platform }));
-```
+## Failures and exit codes
 
-```bash
-$ node check.js
-missing changeset
-$ echo $?
-1
-```
+`CliRuntime.main` reports a failure as a document on stderr, through the audience's renderer: a status line for a typed failure, a tree of rejected values for a schema failure, and a defect's message with a collapsible stack of your own frames (Effect's, Node's and `node_modules` frames hidden). Give an error class a `[CliDoc]()` method to draw itself, or pass a `render` option. Its `details.lines({ status: false })` keeps the run's colour and paths behind your own prefix. The `in: outer › inner` span trail after a failure names only your own spans by default; `env.spans` (`"app"`, `"all"` or `"off"`) chooses, as `env.stackFrames` does for a defect's frames. `"app"` leaves out spans defined in files under `node_modules/@effected/` or `node_modules/effect/`, and fails open: a kit package linked into a workspace, or a bundled program, shows more, never less. A program that is itself installed under `node_modules/@effected/` passes its bin's `import.meta.url` as `env.appModule` to keep its own spans. `env.spansEnvVar` names a variable (say `TOOL_SPANS`) that sets it at run time, as `log.envVar` sets the level. An `Effect.fn` call and its definition are one entry in the trail.
 
-## Features
+- `CliExit.set(code)` records a findings exit code from a handler that still succeeds. Do not provide `CliExit.layer` yourself under `main`, or the code goes to a second, unread cell.
+- `Cancelled` (a prompt quit) exits `130`, and `NotInteractive` (a prompt with nobody to ask) exits `64`, each as one fixed line.
+- A usage error exits `64`. `helpOnUsageError: "stderr"` keeps stdout clean for a caller piping it into `jq`.
+- Without `main`: `CliRuntime.reportFailures()` is the combinator to apply inside your program, and `CliRuntime.reported(error, code)` marks an error you printed yourself.
 
-- `CliLogger.layer(options?)` — replaces the default logger with plain lines, routing every level to stderr by default. The threshold is the `stderrFrom` option (pass `"Error"` to restore the old split), compared ordinally, so a level added upstream lands on the right stream without a change here.
-- `CliLogger.make(options?)` — the `Logger` itself, for composing into a logger set you already have.
-- `CliRuntime.reportFailures(options?)` — reports through your logger, then re-fails with an exit code and the mark that stops the runtime reporting it a second time. `render(error, details)` receives the squashed error and a `FailureDetails` (`{ cause, isDefect }`), so a defect can render differently from a typed failure. Never renders a `CliError.ShowHelp` (already printed by `Command.runWith`) — a `ShowHelp` carrying errors is remapped to `usageExitCode` (default `64`).
-- `CliRuntime.main(program, { platform, logger?, ... })` — assembles a whole program in the one order that reports every failure well: a fresh `CliExit`, the platform layer inside failure reporting, and the logger outermost. `helpOnUsageError: "stderr"` moves the help printed with a parse error onto stderr beside the error, so a caller piping stdout into `jq` gets nothing on a usage error; `--help` and a bare group invocation still print on stdout.
-- `CliRuntime.reported(error, exitCode?)` — marks an error you reported yourself, so the runtime stays quiet about it. A typed `Error` comes back as its own type (the marks are added in place) when it passes `instanceof Error` at runtime; any other value — including one that only satisfies `Error`'s shape structurally — is wrapped in a plain `Error`. 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. It keeps the code you pass: `reported(userError, 3)` exits `3`, not `usageExitCode`.
-- `CliExit.set(code)` — records a findings exit code from a successful program; the highest code set during the run wins. `CliExit.layer` mints a fresh cell per provide (`Layer.fresh`) — `CliRuntime.main` provides it for you.
-- `CliColor.enabled` — `Effect<boolean, never, Stdio>`, the no-color.org decision: off when stdout is not a terminal, or `NO_COLOR` is a non-empty value. `FORCE_COLOR` is ignored.
-- `CliColor.formatterLayer(overrides?)` — core's `CliOutput.Formatter`, coloured by the same decision as `CliColor.enabled`.
-- `SchemaIssueRenderer.render(issue)` — a `SchemaIssue` tree becomes one line per rejected value.
-- `ConfigIssueRenderer.render(error)` — the same rendering, reading `issue` off a `ConfigValidationError`.
+`SchemaIssueRenderer.render(issue)` and `ConfigIssueRenderer.render(error)` turn an issue tree into lines like `unknown key at groups.g.rulesetz`.
 
-Two behaviours worth knowing before you rely on them:
+## Logging
 
-- `CliLogger` honours `References.LogToStderr` as a **one-way** override — it can force everything to stderr, and can never move an error onto stdout.
-- `CliRuntime` keeps an exit code the error already carries via `Runtime.errorExitCode`; the `exitCode` option is a fallback, not an override. An interrupt is left alone.
+`CliLogger` writes plain lines, with no timestamp, level or fiber id, and routes every level to stderr by default (`stderrFrom` narrows it), so stdout carries only the program's output. Pass `env.log` to `main` for **`CliLog`**: a diagnostics level of its own (`level`, or `envVar` such as `TOOL_LOG_LEVEL`, with core's `--log-level` beating both), pretty lines for a person and NDJSON for an agent or CI, an optional NDJSON log file, and `CliLog.component(name)` tags. `CliLog.status(vocab, name, text)` logs a diagnostic with a painted status glyph (its text still sanitised), and `CliTheme.forAudience` applies the kit's "an agent never gets an escape" rule to a theme you paint with yourself.
 
-## Testing
+## Prompts and screens
 
-`@effected/cli/testing` is a separate entrypoint — importing `@effected/cli`
-never pulls it in — for spawning a **built** bin hermetically and reading its
-exit code and streams as data:
+A prompt fires only when `CliInteractive` is true: a human audience, a terminal on stdin and stdout, and `TERM` not `dumb`. Otherwise it answers a default you supply, or fails cleanly.
 
 ```ts
-import { CliTest } from "@effected/cli/testing";
-import * as NodeServices from "@effect/platform-node/NodeServices";
-import { assert, describe, it } from "@effect/vitest";
-import { Effect } from "effect";
+import { CliPrompt } from "@effected/cli";
+import { Flag, Prompt } from "effect/cli";
+
+// Core's prompt as a flag fallback: asks at a terminal, uses "library" in a pipe.
+const profile = Flag.String("profile").pipe(
+  Flag.withFallbackPrompt(
+    CliPrompt.fallback(
+      Prompt.Select({ message: "Profile", choices: [{ title: "library", value: "library" }, { title: "application", value: "application" }] }),
+      { flag: "profile", otherwise: "library" },
+    ),
+  ),
+);
+```
+
+`@effected/cli/ui` adds Ink screens: `CliUi.run`, `prompt` (with an `otherwise`) and `fallback` (for a flag), over the widgets `Select`, `TextInput` (with a `mask` for secrets, always, or from the moment a predicate spots one anywhere in the value, latched until the value is cleared: its `validate` message is drawn unmasked, so never echo the value in it), `MultiSelect`, `Confirm` (with toggles), `Toggle`, `Tabs` and `Viewport`. Your own screens use the key layer (`KeyTable`, `useKeys`, `KeyHelp`) and the theme bridge (`Styled`, `useTheme`, `useGlyphs`, `useTerminalSize`).
 
-describe("check", () => {
-  it.effect("exits 1 when it finds a problem", () =>
-    Effect.gen(function* () {
-      const sandbox = yield* CliTest.sandbox({ path: process.env.PATH ?? "" });
-      const result = yield* CliTest.run("./dist/check.js", ["--strict"], {
-        sandbox,
-        execPath: process.execPath,
-      });
-      assert.strictEqual(result.exitCode, 1);
-      assert.include(result.stdout, "missing changeset");
-    }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
-  );
+```tsx
+import { CliUi, Select } from "@effected/cli/ui";
+
+const pickProfile = Select.screen({
+  message: "Profile",
+  choices: [
+    { label: "library", value: "library" },
+    { label: "application", value: "application" },
+  ],
 });
+
+const profile = CliUi.prompt(pickProfile, { otherwise: "library" });
+```
+
+`CliUi.map(screen, f)` maps a screen's answer and leaves a cancel alone, so a `Confirm` can back a boolean flag ("confirm, or `--yes`"):
+
+```ts
+import { CliUi, Confirm } from "@effected/cli/ui";
+import { Flag } from "effect/cli";
+
+const yes = Flag.Boolean("yes").pipe(
+  Flag.withFallbackPrompt(
+    CliUi.fallback(
+      CliUi.map(Confirm.screen({ message: "Publish?" }), (result) => result.confirmed),
+      { flag: "yes", otherwise: false },
+    ),
+  ),
+);
 ```
 
-`CliTest.sandbox({ path })` mints a scoped temp directory with a fresh `HOME`
-and `XDG_{CONFIG,DATA,STATE,CACHE}_HOME`, `NO_COLOR: "1"`, and the `path` you
-pass as `PATH` — the host environment is never inherited. `CliTest.run` never
-leaves `stdin` as an open pipe: when you omit it, or pass `""`, the child
-receives an already-ended empty input, so a stdin-reading bin cannot hang the
-test.
+## Live views
+
+`CliUi.live` folds a stream or a `PubSub` subscription of events into state, and draws **runs** with Ink while they are going: a run starts at `isStart`, redraws on a tick, and commits its final frame at `isTerminal`. Log lines go above the frame through `handle.logConsole`. End with `handle.close`, which folds everything still queued. When nobody is watching (a pipe, an agent, CI), each run's final frame prints once instead: give the view a `final: (state) => Document` and that run prints the document with no Ink or React loaded at all; `render` is then never called on such a run, not even to build an unused string. `render: CliUi.lazyView(() => import("./view.js"))` keeps the view's module, and React, off every run until one draws. `DocView` draws a `Doc` document inside a view byte for byte as `Doc.print` would, and `UiProvider` with `CliUi.context` gives an Ink tree you mount yourself the same theme.
+
+## Testing
+
+- **`@effected/cli/testing`**: `CliTest.sandbox` and `CliTest.run` spawn a built bin hermetically and return `{ exitCode, stdout, stderr }` as data. `TestTerminal` drives core's prompts.
+- **`@effected/cli/ui/testing`**: `CliUiTest.render` mounts a screen on in-memory streams (`press`, `type`, `chunk`, `frame`, `result`). `view` mounts a display-only element, `session` drives a whole command's screens (its `transcript` shows what reached the terminal, a live view's `logConsole` lines included, `stdoutWritten`/`stderrWritten` each stream alone as raw bytes, `stdoutTranscript`/`stderrTranscript` each stream alone as plain text, and `renderPath: "production"` makes `clear` observable), and `live` mounts a live view on the production render path with a `TestClock` tick. `CliUiTest.serializer` prints frames as token markup in snapshots: register it in the Vitest config with `snapshotSerializers: ["@effected/cli/ui/testing/serializer"]`, or with `expect.addSnapshotSerializer`. Snapshots are the one place a test needs `expect`, since `assert` has no snapshot form.
+
+In-process, provide `layerTest`s from `@effected/env` and `CliTheme.layerTest`, swap in a capturing `Console`, and assert on both streams. Neither testing entrypoint is reachable from a CLI's runtime imports.
+
+## Documentation
+
+Guides for every part, and the full API reference, are at [effected.spencerbeg.gs/cli](https://effected.spencerbeg.gs/cli): [getting started](https://effected.spencerbeg.gs/cli/getting-started), [audiences and output](https://effected.spencerbeg.gs/cli/output), [prompts and screens](https://effected.spencerbeg.gs/cli/prompts), [live views](https://effected.spencerbeg.gs/cli/live-views), [testing](https://effected.spencerbeg.gs/cli/testing) and [advanced](https://effected.spencerbeg.gs/cli/advanced).
 
 ## License