@cruxy/cli 0.13.0 → 0.14.0

package/dist/approval/prompt.js

@@ -37,16 +37,30 @@ export async function promptForApproval(request, io) {
 export function render(request, color) {
     const t = themeForColor(color);
     const destructive = request.tier === "destructive";
-    // The risk mark carries meaning by shape (`!` vs `?`), not by color alone —
-    // so it survives NO_COLOR (U.1 accessibility groundwork).
+    // Risk survives all three degradations (U.11): the mark carries it by *shape*
+    // (`!` vs `?`) for NO_COLOR, and the label carries it by *word*
+    // (`(destructive)` / `(mutate)` / `(read)`) — never by hue alone, and legible
+    // to a screen reader that would otherwise read `!` as "exclamation mark".
     const mark = destructive ? t.danger(t.strong("!")) : t.warning("?");
-    const label = destructive ? t.danger(t.strong(" (destructive)")) : "";
+    const label = tierLabel(request.tier, t);
     const lines = [];
     lines.push(`${mark} cruxy wants to ${t.strong(request.summary)}${label}`);
     lines.push(detail(request, t));
     lines.push(choices(request.scope, t));
     return lines.filter((l) => l !== "").join("\n") + " ";
 }
+/** The worded risk tag, colored by tier — always present, so meaning never
+ * rides on the `!`/`?` shape or its color alone. */
+function tierLabel(tier, t) {
+    switch (tier) {
+        case "destructive":
+            return t.danger(t.strong(" (destructive)"));
+        case "mutate":
+            return t.warning(" (mutate)");
+        case "read":
+            return t.muted(" (read)");
+    }
+}
 /** The action detail: a diff for file actions, the command + cwd for shell/test. */
 function detail(request, t) {
     if (request.action.kind === "shell" || request.action.kind === "test") {

package/dist/components/fuzzy.js

@@ -106,7 +106,9 @@ export async function fuzzyFind(items, opts, io = defaultComponentIO()) {
             lines.push(t.heading(opts.title));
         lines.push(`${t.accent(g.caret)} ${query}${t.muted(g.cursorBar)}`);
         if (ranked.length === 0) {
-            lines.push(t.muted("  no results — backspace to widen"));
+            // No dead-end: the only escapes (backspace, esc) stay advertised even
+            // when nothing matches — the user is never stranded with no visible exit.
+            lines.push(t.muted("  no results — backspace to widen · esc cancel"));
         }
         else {
             // Keep the highlighted row inside the viewport.
@@ -122,6 +124,10 @@ export async function fuzzyFind(items, opts, io = defaultComponentIO()) {
             if (hidden > 0)
                 lines.push(t.muted(`  ${g.ellipsis} ${hidden} more`));
         }
+        // Persistent key hint (U.11 keyboard-completeness): every operable key is
+        // advertised, mirroring selectList — type filters, arrows move, enter
+        // selects, esc cancels. Present in both the results and no-results states.
+        lines.push(t.muted(`  type to filter ${g.sep} ${g.caretUp}/${g.caretDown} move ${g.sep} enter select ${g.sep} esc cancel`));
         frame.render(lines);
     };
     io.keys.begin();

package/dist/onboarding/steps.js

@@ -93,7 +93,10 @@ export async function firstWinStep(io, deps) {
     io.write(`\nRun a quick demo now — let cruxy summarize this repo? ${col.muted("[Y/n]")} `);
     const key = (await io.readKey()).toLowerCase();
     io.write("\n");
-    if (key === "n")
+    // Decline on an explicit `n`, and treat Ctrl-C / EOF / escape (readKey → "")
+    // as a clean cancel rather than "proceed": a cancel must never launch a task.
+    // Enter (readKey → "\n") keeps the `[Y/n]` default and runs the demo.
+    if (key === "n" || key === "")
         return { status: "skipped" };
     await deps.runTask(FIRST_WIN_PROMPT);
     return { status: "ok" };

package/dist/render/capabilities.d.ts

@@ -1,4 +1,11 @@
 import type { RenderCapabilities, RenderStream } from "./types.js";
+/**
+ * Reduced-motion (U.11) — the ecosystem `NO_MOTION` signal, the explicit cruxy
+ * knob `CRUXY_REDUCED_MOTION`, and `CRUXY_NO_SPINNER` kept as an alias flowing
+ * through this one axis. A screen reader implies it (no live region to animate).
+ * The single source of the spinner gate.
+ */
+export declare function detectReducedMotion(env?: NodeJS.ProcessEnv): boolean;
 /**
  * Probe the environment once and reduce it to {@link RenderCapabilities}. Pure
  * given its inputs (stream + env are injectable), so every row of the
@@ -6,7 +13,8 @@ import type { RenderCapabilities, RenderStream } from "./types.js";
  *
  * Color reuses {@link shouldUseColor} (NO_COLOR / FORCE_COLOR / TTY) with one
  * refinement: `TERM=dumb` terminals get no color even though they are TTYs.
- * Cursor control and color are independent axes — a NO_COLOR terminal still
- * supports in-place status updates; a dumb terminal supports neither.
+ * The axes are independent (U.1/U.11): a NO_COLOR terminal still supports
+ * in-place status updates; a dumb terminal supports neither; reduced motion and
+ * screen-reader mode compose orthogonally with color and unicode.
  */
 export declare function detectCapabilities(stream?: RenderStream, env?: NodeJS.ProcessEnv): RenderCapabilities;

package/dist/render/capabilities.js

@@ -1,5 +1,21 @@
 import { shouldUseColor } from "../errors/index.js";
-import { detectUnicode } from "../theme/index.js";
+import { detectScreenReader, detectUnicode } from "../theme/index.js";
+/** Set-and-non-empty (the NO_COLOR convention): any non-empty value counts. */
+function isSet(value) {
+    return value !== undefined && value !== "";
+}
+/**
+ * Reduced-motion (U.11) — the ecosystem `NO_MOTION` signal, the explicit cruxy
+ * knob `CRUXY_REDUCED_MOTION`, and `CRUXY_NO_SPINNER` kept as an alias flowing
+ * through this one axis. A screen reader implies it (no live region to animate).
+ * The single source of the spinner gate.
+ */
+export function detectReducedMotion(env = process.env) {
+    return (isSet(env.NO_MOTION) ||
+        isSet(env.CRUXY_REDUCED_MOTION) ||
+        isSet(env.CRUXY_NO_SPINNER) ||
+        detectScreenReader(env));
+}
 /**
  * Probe the environment once and reduce it to {@link RenderCapabilities}. Pure
  * given its inputs (stream + env are injectable), so every row of the
@@ -7,20 +23,24 @@ import { detectUnicode } from "../theme/index.js";
  *
  * Color reuses {@link shouldUseColor} (NO_COLOR / FORCE_COLOR / TTY) with one
  * refinement: `TERM=dumb` terminals get no color even though they are TTYs.
- * Cursor control and color are independent axes — a NO_COLOR terminal still
- * supports in-place status updates; a dumb terminal supports neither.
+ * The axes are independent (U.1/U.11): a NO_COLOR terminal still supports
+ * in-place status updates; a dumb terminal supports neither; reduced motion and
+ * screen-reader mode compose orthogonally with color and unicode.
  */
 export function detectCapabilities(stream = process.stdout, env = process.env) {
     const tty = Boolean(stream.isTTY);
     const dumb = env.TERM === "dumb";
     const cursor = tty && !dumb;
+    const reducedMotion = detectReducedMotion(env);
     return {
         tty,
         color: shouldUseColor(stream, env) && !dumb,
         cursor,
-        // Same set-and-non-empty convention as NO_COLOR: any value disables.
-        spinner: cursor &&
-            !(env.CRUXY_NO_SPINNER !== undefined && env.CRUXY_NO_SPINNER !== ""),
+        // Motion is the single gate now: CRUXY_NO_SPINNER flows through it (alias),
+        // as do NO_MOTION / CRUXY_REDUCED_MOTION and an implied screen reader.
+        spinner: cursor && !reducedMotion,
+        reducedMotion,
+        screenReader: detectScreenReader(env),
         // Unicode glyph safety (U.1) — independent of color. dumb / CRUXY_ASCII →
         // ASCII glyphs; everything else (incl. pipes) keeps unicode.
         unicode: detectUnicode(env),

package/dist/render/index.d.ts

@@ -1,15 +1,19 @@
 import type { RenderStream, StreamRenderer } from "./types.js";
 export type { ProgressState, RenderCapabilities, RenderPhase, RenderStream, StreamRenderer, TokenUsage, ToolLifecycleEvent, } from "./types.js";
-export { detectCapabilities } from "./capabilities.js";
+export { detectCapabilities, detectReducedMotion } from "./capabilities.js";
 export { composeStatusLine, describePhase, ELAPSED_AFTER_MS, formatElapsed, formatTokens, phaseIdentity, } from "./state.js";
 export { renderActionPreview, PREVIEW_MAX_LINES } from "./diff.js";
 export { createStreamHighlighter, defaultLineHighlighter, type HighlightCarry, type LineHighlighter, type StreamHighlighter, } from "./highlight.js";
 export { PlainRenderer } from "./plain-renderer.js";
+export { ScreenReaderRenderer } from "./screen-reader-renderer.js";
 export { TtyRenderer } from "./tty-renderer.js";
 /**
- * Build the renderer for the detected environment: the managed-live-region
- * {@link TtyRenderer} when cursor control is safe, otherwise the append-only
- * {@link PlainRenderer} (pipes, CI, `TERM=dumb`). Everything downstream talks
- * to the {@link StreamRenderer} interface and never re-probes the terminal.
+ * Build the renderer for the detected environment (U.11 adds the first branch):
+ * - `screenReader` → the linear, worded {@link ScreenReaderRenderer}, regardless
+ *   of cursor support (a screen-reader TTY must not get the live region);
+ * - else cursor-safe → the managed-live-region {@link TtyRenderer} (static, no
+ *   timer, when `reducedMotion`);
+ * - else → the append-only {@link PlainRenderer} (pipes, CI, `TERM=dumb`).
+ * Everything downstream talks to {@link StreamRenderer} and never re-probes.
  */
 export declare function createRenderer(out?: RenderStream, err?: RenderStream, env?: NodeJS.ProcessEnv): StreamRenderer;

package/dist/render/index.js

@@ -1,20 +1,27 @@
 import { detectCapabilities } from "./capabilities.js";
 import { PlainRenderer } from "./plain-renderer.js";
+import { ScreenReaderRenderer } from "./screen-reader-renderer.js";
 import { TtyRenderer } from "./tty-renderer.js";
-export { detectCapabilities } from "./capabilities.js";
+export { detectCapabilities, detectReducedMotion } from "./capabilities.js";
 export { composeStatusLine, describePhase, ELAPSED_AFTER_MS, formatElapsed, formatTokens, phaseIdentity, } from "./state.js";
 export { renderActionPreview, PREVIEW_MAX_LINES } from "./diff.js";
 export { createStreamHighlighter, defaultLineHighlighter, } from "./highlight.js";
 export { PlainRenderer } from "./plain-renderer.js";
+export { ScreenReaderRenderer } from "./screen-reader-renderer.js";
 export { TtyRenderer } from "./tty-renderer.js";
 /**
- * Build the renderer for the detected environment: the managed-live-region
- * {@link TtyRenderer} when cursor control is safe, otherwise the append-only
- * {@link PlainRenderer} (pipes, CI, `TERM=dumb`). Everything downstream talks
- * to the {@link StreamRenderer} interface and never re-probes the terminal.
+ * Build the renderer for the detected environment (U.11 adds the first branch):
+ * - `screenReader` → the linear, worded {@link ScreenReaderRenderer}, regardless
+ *   of cursor support (a screen-reader TTY must not get the live region);
+ * - else cursor-safe → the managed-live-region {@link TtyRenderer} (static, no
+ *   timer, when `reducedMotion`);
+ * - else → the append-only {@link PlainRenderer} (pipes, CI, `TERM=dumb`).
+ * Everything downstream talks to {@link StreamRenderer} and never re-probes.
  */
 export function createRenderer(out = process.stdout, err = process.stderr, env = process.env) {
     const caps = detectCapabilities(out, env);
+    if (caps.screenReader)
+        return new ScreenReaderRenderer(caps, out, err);
     return caps.cursor
         ? new TtyRenderer(caps, out)
         : new PlainRenderer(caps, out, err);

package/dist/render/plain-renderer.d.ts

@@ -1,6 +1,6 @@
 import type { ActionPreview } from "../tools/types.js";
 import { type Theme } from "../theme/index.js";
-import type { RenderCapabilities, RenderStream, StreamRenderer, ToolLifecycleEvent } from "./types.js";
+import type { ProgressState, RenderCapabilities, RenderPhase, RenderStream, StreamRenderer, ToolLifecycleEvent } from "./types.js";
 /**
  * The append-only renderer for pipes, CI, and cursor-less terminals. Emits no
  * cursor-control sequences ever, and no color unless the capabilities say so
@@ -30,8 +30,8 @@ export declare class PlainRenderer implements StreamRenderer {
     note(text: string): void;
     preview(preview: ActionPreview): void;
     status(): void;
-    setPhase(): void;
-    progress(): void;
+    setPhase(phase: RenderPhase | null): void;
+    progress(state: ProgressState | null): void;
     toolLifecycle(event: ToolLifecycleEvent): void;
     promptResolved(): void;
     endTurn(): void;

package/dist/render/plain-renderer.js

@@ -59,12 +59,20 @@ export class PlainRenderer {
     status() {
         // Append-only medium: transient state is dropped by design.
     }
-    setPhase() {
+    // setPhase / progress declare their StreamRenderer params because the
+    // ScreenReaderRenderer subclass overrides them to announce (the override must
+    // be signature-compatible). In the plain medium they are no-ops: there is no
+    // live region to update, so the guard simply returns.
+    setPhase(phase) {
         // Phases are live-region state; there is no live region here (U.4).
+        if (phase !== null)
+            return;
     }
-    progress() {
+    progress(state) {
         // The committed plan trail (C.31, via PromptIO) is the record in this
         // medium; a live [i/n] prefix would just duplicate it line by line.
+        if (state !== null)
+            return;
     }
     toolLifecycle(event) {
         if (event.event === "start") {

package/dist/render/screen-reader-renderer.d.ts

@@ -0,0 +1,45 @@
+import { PlainRenderer } from "./plain-renderer.js";
+import type { ProgressState, RenderCapabilities, RenderPhase, RenderStream, ToolLifecycleEvent } from "./types.js";
+/**
+ * The screen-reader renderer (U.11): {@link PlainRenderer}'s linear,
+ * append-only, zero-cursor-control output — plus two things a screen reader
+ * needs that the plain path drops.
+ *
+ * 1. **Worded status.** Its theme resolves the {@link SCREEN_READER_GLYPHS}
+ *    table (via `caps.screenReader`), so every inherited code path that writes
+ *    `theme.glyph.success` prints `done` instead of `✓`, `failed` for `✗`, etc.
+ *    Nothing here special-cases it — the glyph table does the work.
+ *
+ * 2. **Announced state.** A screen reader cannot see an in-place live region, so
+ *    each state change is emitted as its own committed line (never a redraw):
+ *    a phase becomes `working: read_file src/x.ts`, a tool run brackets as
+ *    `working: …` → `done …`, and plan progress announces `step 2 of 5: title`.
+ *    Announcements are deduped by phase *identity* so token-count updates within
+ *    the same activity don't repeat a line.
+ *
+ * Everything else — text streaming, `endSegment`, `note`, `preview` — is
+ * inherited unchanged. This is the whole of screen-reader mode: no parallel
+ * path, no behavior change to the plain or TTY renderers.
+ */
+export declare class ScreenReaderRenderer extends PlainRenderer {
+    /** Identity of the last phase announced, so we speak each activity once. */
+    private lastPhaseId;
+    /** Text of the last progress line announced, to avoid repeats. */
+    private lastProgress;
+    constructor(caps: RenderCapabilities, out: RenderStream, err: RenderStream);
+    /**
+     * Announce a phase transition as a committed line. `null`, `awaiting-approval`
+     * (the prompt block is its own announcement), and `calling-tool` (announced by
+     * {@link toolLifecycle}) are silent; repeats of the same activity are deduped.
+     */
+    setPhase(phase: RenderPhase | null): void;
+    /** Announce plan-step progress as `step i of n: title`, deduped. */
+    progress(state: ProgressState | null): void;
+    /**
+     * Bracket a tool call with two committed lines — `working: label` on start,
+     * `done/failed label` on end — so a screen-reader user hears both that a call
+     * began (crucial for long ones) and how it resolved. The end note + honest
+     * duration is the inherited plain behavior; only the start line is added.
+     */
+    toolLifecycle(event: ToolLifecycleEvent): void;
+}

package/dist/render/screen-reader-renderer.js

@@ -0,0 +1,75 @@
+import { PlainRenderer } from "./plain-renderer.js";
+import { describePhase, phaseIdentity } from "./state.js";
+/**
+ * The screen-reader renderer (U.11): {@link PlainRenderer}'s linear,
+ * append-only, zero-cursor-control output — plus two things a screen reader
+ * needs that the plain path drops.
+ *
+ * 1. **Worded status.** Its theme resolves the {@link SCREEN_READER_GLYPHS}
+ *    table (via `caps.screenReader`), so every inherited code path that writes
+ *    `theme.glyph.success` prints `done` instead of `✓`, `failed` for `✗`, etc.
+ *    Nothing here special-cases it — the glyph table does the work.
+ *
+ * 2. **Announced state.** A screen reader cannot see an in-place live region, so
+ *    each state change is emitted as its own committed line (never a redraw):
+ *    a phase becomes `working: read_file src/x.ts`, a tool run brackets as
+ *    `working: …` → `done …`, and plan progress announces `step 2 of 5: title`.
+ *    Announcements are deduped by phase *identity* so token-count updates within
+ *    the same activity don't repeat a line.
+ *
+ * Everything else — text streaming, `endSegment`, `note`, `preview` — is
+ * inherited unchanged. This is the whole of screen-reader mode: no parallel
+ * path, no behavior change to the plain or TTY renderers.
+ */
+export class ScreenReaderRenderer extends PlainRenderer {
+    /** Identity of the last phase announced, so we speak each activity once. */
+    lastPhaseId = "";
+    /** Text of the last progress line announced, to avoid repeats. */
+    lastProgress = "";
+    constructor(caps, out, err) {
+        super(caps, out, err);
+    }
+    /**
+     * Announce a phase transition as a committed line. `null`, `awaiting-approval`
+     * (the prompt block is its own announcement), and `calling-tool` (announced by
+     * {@link toolLifecycle}) are silent; repeats of the same activity are deduped.
+     */
+    setPhase(phase) {
+        const id = phaseIdentity(phase);
+        if (id === this.lastPhaseId)
+            return;
+        this.lastPhaseId = id;
+        if (phase === null ||
+            phase.kind === "awaiting-approval" ||
+            phase.kind === "calling-tool") {
+            return;
+        }
+        this.note(describePhase(phase, this.theme.glyph));
+    }
+    /** Announce plan-step progress as `step i of n: title`, deduped. */
+    progress(state) {
+        if (state === null) {
+            this.lastProgress = "";
+            return;
+        }
+        const line = `step ${state.step} of ${state.of}: ${state.title}`;
+        if (line === this.lastProgress)
+            return;
+        this.lastProgress = line;
+        this.note(line);
+    }
+    /**
+     * Bracket a tool call with two committed lines — `working: label` on start,
+     * `done/failed label` on end — so a screen-reader user hears both that a call
+     * began (crucial for long ones) and how it resolved. The end note + honest
+     * duration is the inherited plain behavior; only the start line is added.
+     */
+    toolLifecycle(event) {
+        if (event.event === "start") {
+            super.toolLifecycle(event); // records the start time (silent in plain)
+            this.note(`${this.theme.glyph.running}: ${event.label}`);
+            return;
+        }
+        super.toolLifecycle(event); // commits `done/failed label (duration)`
+    }
+}

package/dist/render/types.d.ts

@@ -20,8 +20,22 @@ export interface RenderCapabilities {
     color: boolean;
     /** Cursor-control sequences are safe (`tty` and not `TERM=dumb`). */
     cursor: boolean;
-    /** Animation is welcome (`cursor` and CRUXY_NO_SPINNER unset). */
+    /** Animation is welcome (`cursor` and motion is not reduced). */
     spinner: boolean;
+    /**
+     * Motion is reduced (U.11): no spinner animation/timer, no in-place
+     * re-animation — state survives as static text, only movement stops. True
+     * under `CRUXY_NO_SPINNER` (alias) / `NO_MOTION` / `CRUXY_REDUCED_MOTION`, and
+     * implied by `screenReader`. The one axis the spinner gate keys off.
+     */
+    reducedMotion: boolean;
+    /**
+     * Screen-reader mode (U.11): plain, linear, announce-friendly output — no
+     * live-region redraws (each state change is a committed line), no spinners,
+     * status glyphs rendered as words. Opt-in via `CRUXY_SCREEN_READER` /
+     * `ACCESSIBLE`; routes rendering to the linear path regardless of `cursor`.
+     */
+    screenReader: boolean;
     /** Unicode glyphs are safe (U.1) — false under `TERM=dumb` / `CRUXY_ASCII`;
      * independent of `color`. Drives the theme's glyph table, not its stylers. */
     unicode: boolean;

package/dist/theme/resolve.d.ts

@@ -1,14 +1,15 @@
 import { type Theme, type ThemeCapabilities } from "./tokens.js";
 /**
- * Theme resolution (U.1) — the ONE place picocolors is used. The two axes are
+ * Theme resolution (U.1/U.11) — the ONE place picocolors is used. The axes are
  * fully independent by construction:
  *
  * - `color` drives the stylers only. `pc.createColors(false)` is the identity,
  *   so NO_COLOR yields zero ANSI bytes (dim/bold vanish too) — asserted in the
  *   tests.
- * - `unicode` drives the glyph table only. It never touches color: a NO_COLOR
- *   unicode terminal still prints ✓/✗ (glyphs aren't ANSI), and a colored
- *   CRUXY_ASCII terminal prints a colored `[ok]`.
+ * - the glyph table is chosen by `screenReader` (words) → else `unicode`
+ *   (✓/✗) → else ASCII (`[ok]`/`[x]`). Never touches color: a NO_COLOR unicode
+ *   terminal still prints ✓/✗ (glyphs aren't ANSI), a colored CRUXY_ASCII
+ *   terminal prints a colored `[ok]`, and a screen reader gets colorless words.
  */
 export declare function resolveTheme(caps: ThemeCapabilities): Theme;
 /**
@@ -23,10 +24,20 @@ export declare function resolveTheme(caps: ThemeCapabilities): Theme;
  * signature change.
  */
 export declare function detectUnicode(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Whether the user asked for screen-reader mode (U.11) — opt-in via
+ * `CRUXY_SCREEN_READER` or the ecosystem `ACCESSIBLE` flag (set-and-non-empty).
+ * Deliberately NOT inferred from a pipe: auto-wording every non-TTY stream would
+ * change existing CI/plain output. The single source of the rule, called by
+ * `render/capabilities.ts` (to fill `RenderCapabilities.screenReader`) and by
+ * the boolean-seam {@link themeForColor} surfaces (approval, plan, onboarding).
+ */
+export declare function detectScreenReader(env?: NodeJS.ProcessEnv): boolean;
 /**
  * Build a theme for a surface that only knows a `color` boolean (the U.3
- * PromptIO, error formatting, plan/onboarding/CLI copy). Unicode is detected
- * from the environment so these surfaces still degrade on dumb terminals,
- * with no change to their public boolean signatures.
+ * PromptIO, error formatting, plan/onboarding/CLI copy). Unicode and
+ * screen-reader mode are detected from the environment so these surfaces still
+ * degrade on dumb terminals and speak words to a screen reader, with no change
+ * to their public boolean signatures.
  */
 export declare function themeForColor(color: boolean, env?: NodeJS.ProcessEnv): Theme;

package/dist/theme/resolve.js

@@ -1,19 +1,24 @@
 import pc from "picocolors";
-import { ASCII_GLYPHS, UNICODE_GLYPHS, } from "./tokens.js";
+import { ASCII_GLYPHS, SCREEN_READER_GLYPHS, UNICODE_GLYPHS, } from "./tokens.js";
 /**
- * Theme resolution (U.1) — the ONE place picocolors is used. The two axes are
+ * Theme resolution (U.1/U.11) — the ONE place picocolors is used. The axes are
  * fully independent by construction:
  *
  * - `color` drives the stylers only. `pc.createColors(false)` is the identity,
  *   so NO_COLOR yields zero ANSI bytes (dim/bold vanish too) — asserted in the
  *   tests.
- * - `unicode` drives the glyph table only. It never touches color: a NO_COLOR
- *   unicode terminal still prints ✓/✗ (glyphs aren't ANSI), and a colored
- *   CRUXY_ASCII terminal prints a colored `[ok]`.
+ * - the glyph table is chosen by `screenReader` (words) → else `unicode`
+ *   (✓/✗) → else ASCII (`[ok]`/`[x]`). Never touches color: a NO_COLOR unicode
+ *   terminal still prints ✓/✗ (glyphs aren't ANSI), a colored CRUXY_ASCII
+ *   terminal prints a colored `[ok]`, and a screen reader gets colorless words.
  */
 export function resolveTheme(caps) {
     const c = pc.createColors(caps.color);
-    const glyph = caps.unicode ? UNICODE_GLYPHS : ASCII_GLYPHS;
+    const glyph = caps.screenReader
+        ? SCREEN_READER_GLYPHS
+        : caps.unicode
+            ? UNICODE_GLYPHS
+            : ASCII_GLYPHS;
     const strong = c.bold;
     const indent = (text, level = 1) => {
         const pad = "  ".repeat(Math.max(0, level));
@@ -62,12 +67,29 @@ export function detectUnicode(env = process.env) {
         return false;
     return true;
 }
+/**
+ * Whether the user asked for screen-reader mode (U.11) — opt-in via
+ * `CRUXY_SCREEN_READER` or the ecosystem `ACCESSIBLE` flag (set-and-non-empty).
+ * Deliberately NOT inferred from a pipe: auto-wording every non-TTY stream would
+ * change existing CI/plain output. The single source of the rule, called by
+ * `render/capabilities.ts` (to fill `RenderCapabilities.screenReader`) and by
+ * the boolean-seam {@link themeForColor} surfaces (approval, plan, onboarding).
+ */
+export function detectScreenReader(env = process.env) {
+    const set = (v) => v !== undefined && v !== "";
+    return set(env.CRUXY_SCREEN_READER) || set(env.ACCESSIBLE);
+}
 /**
  * Build a theme for a surface that only knows a `color` boolean (the U.3
- * PromptIO, error formatting, plan/onboarding/CLI copy). Unicode is detected
- * from the environment so these surfaces still degrade on dumb terminals,
- * with no change to their public boolean signatures.
+ * PromptIO, error formatting, plan/onboarding/CLI copy). Unicode and
+ * screen-reader mode are detected from the environment so these surfaces still
+ * degrade on dumb terminals and speak words to a screen reader, with no change
+ * to their public boolean signatures.
  */
 export function themeForColor(color, env = process.env) {
-    return resolveTheme({ color, unicode: detectUnicode(env) });
+    return resolveTheme({
+        color,
+        unicode: detectUnicode(env),
+        screenReader: detectScreenReader(env),
+    });
 }

package/dist/theme/tokens.d.ts

@@ -90,10 +90,16 @@ export interface Theme {
     readonly color: boolean;
     readonly unicode: boolean;
 }
-/** The two axes a theme is resolved from — a structural subset of RenderCapabilities. */
+/** The axes a theme is resolved from — a structural subset of RenderCapabilities. */
 export interface ThemeCapabilities {
     color: boolean;
     unicode: boolean;
+    /**
+     * Screen-reader mode (U.11): status glyphs render as words. Optional so every
+     * existing `{color, unicode}` caller is unchanged (defaults to off). When set
+     * it takes precedence over `unicode` for the glyph table.
+     */
+    screenReader?: boolean;
 }
 /** The unicode glyph table (real terminals). */
 export declare const UNICODE_GLYPHS: ThemeGlyphs;
@@ -102,3 +108,12 @@ export declare const UNICODE_GLYPHS: ThemeGlyphs;
  * mojibake — the intentional U.1 degradation for unicode-unsafe terminals.
  */
 export declare const ASCII_GLYPHS: ThemeGlyphs;
+/**
+ * The screen-reader glyph table (U.11): the status glyphs a screen reader would
+ * otherwise announce as bare punctuation are spelled as words — `done`,
+ * `failed`, `working`, `pending` — so `✓ read_file` becomes `done read_file`.
+ * Structural glyphs stay ASCII-legible (a pointer/caret has no useful word).
+ * This is the entire "worded status" of screen-reader mode: swap the table,
+ * reuse every existing renderer/theme code path unchanged.
+ */
+export declare const SCREEN_READER_GLYPHS: ThemeGlyphs;

package/dist/theme/tokens.js

@@ -50,3 +50,30 @@ export const ASCII_GLYPHS = {
     spinnerFrames: ["-", "\\", "|", "/"],
     spinnerStatic: "~",
 };
+/**
+ * The screen-reader glyph table (U.11): the status glyphs a screen reader would
+ * otherwise announce as bare punctuation are spelled as words — `done`,
+ * `failed`, `working`, `pending` — so `✓ read_file` becomes `done read_file`.
+ * Structural glyphs stay ASCII-legible (a pointer/caret has no useful word).
+ * This is the entire "worded status" of screen-reader mode: swap the table,
+ * reuse every existing renderer/theme code path unchanged.
+ */
+export const SCREEN_READER_GLYPHS = {
+    success: "done",
+    failure: "failed",
+    pending: "pending",
+    running: "working",
+    pointer: ">",
+    caret: ">",
+    arrow: "->",
+    caretUp: "up",
+    caretDown: "down",
+    cursorBar: "",
+    bullet: "-",
+    sep: "-",
+    ellipsis: "...",
+    play: ">",
+    // Unused in the linear screen-reader path (no live region), kept legible.
+    spinnerFrames: ["working"],
+    spinnerStatic: "working",
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cruxy/cli",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {