Updated docs.

Author: uhop

AGENTS.md

@@ -90,7 +90,7 @@ options.bash/
 - **Global variables** use `module_name` prefix (e.g., `ansi_style_colors`, `args_program_name`).
 - **Include guards**: every module checks for a sentinel function at the top and returns early if already loaded.
 - **Auto-dependency loading**: modules resolve their own dependencies relative to `BASH_SOURCE`.
-- **No simple command name pollution** by default can be disabled by setting `ANSI_NO_SIMPLE_COMMAND_NAMES=1` before sourcing.
+- **Simple command names** (`RED`, `BOLD`, `RESET_ALL`, etc.) are defined by default. Suppress with `ANSI_NO_SIMPLE_COMMAND_NAMES=1` before sourcing.
 
 ## Architecture
 
@@ -183,7 +183,8 @@ args::parse "$@"
 - Every module is independently sourceable (dependencies are auto-resolved).
 - `ansi.sh` and `ansi-tput.sh` are mutually exclusive — source only one.
 - Use `ansi::out` / `box::out` / `string::out` instead of raw `echo` for terminal-safe output.
-- Error output functions (`ansi::err`, `box::err`, `string::err`) write to stderr and return 1.
+- Warning output (`::warn`) writes to stderr and returns 0 — safe under `set -e`.
+- Error output (`::err`) writes to stderr and returns 1.
 - Wiki documentation lives in the `wiki/` submodule.
 - Automated tests live in `tests/` — run with `bash tests/run.sh`.
 - Manual tests (visual inspection) live in `tests/manual/`.

ARCHITECTURE.md

@@ -30,8 +30,7 @@ wiki/                 # GitHub wiki documentation (git submodule)
 
 ```
 string.sh             ← no dependencies (lowest level)
-    ↑
-ansi-utils.sh         ← loads string.sh (via ansi.sh or ansi-tput.sh)
+ansi-utils.sh         ← no dependencies (shared helpers for ansi.sh / ansi-tput.sh)
     ↑
 ansi.sh               ← loads ansi-utils.sh (raw escape sequences)
 ansi-tput.sh          ← loads ansi-utils.sh (tput-based, alternative to ansi.sh)
@@ -50,9 +49,9 @@ args-completion.sh    ← loads args.sh (registers args::on_options hook)
 | Module | Auto-loads |
 |---|---|
 | `string.sh` | _(nothing)_ |
-| `ansi-utils.sh` | _(nothing, but expects `string.sh` functions or degrades gracefully)_ |
-| `ansi.sh` | `ansi-utils.sh` → `string.sh` |
-| `ansi-tput.sh` | `ansi-utils.sh` → `string.sh` |
+| `ansi-utils.sh` | _(nothing)_ |
+| `ansi.sh` | `ansi-utils.sh` |
+| `ansi-tput.sh` | `ansi-utils.sh` |
 | `box.sh` | `string.sh` |
 | `args.sh` | _(nothing)_ |
 | `args-help.sh` | `ansi.sh`, `string.sh`, `box.sh` |
@@ -79,11 +78,11 @@ This means modules can be sourced multiple times safely, and dependency loading
 
 ### Terminal-aware output
 
-All output functions (`ansi::out`, `box::out`, `string::out`) detect whether stdout/stderr is a terminal:
+Output functions detect whether stdout/stderr is a terminal:
 - **Terminal**: output includes ANSI escape codes.
 - **Pipe/file**: escape codes are automatically stripped.
 
-The check is `[[ -t 1 || -z "$TERM" ]]` (fd 1 for stdout, fd 2 for stderr).
+Stdout functions (`::out`): check `[[ -t 1 || -z "$TERM" ]]`. Stderr functions (`::err`, `::warn`): check `[[ -t 2 || -z "$TERM" ]]`. `::err` returns 1 (signals failure); `::warn` returns 0 (safe under `set -e`).
 
 ### ANSI implementations
 

llms.txt

@@ -40,6 +40,7 @@ String utilities. No dependencies.
 - `string::make_pad LENGTH [CHAR]` — create a padding string of given length.
 - `string::pad STRING LENGTH [ALIGN] [CHAR]` — pad string to length. ALIGN: `left`/`l`, `right`/`r`, `center`/`c`.
 - `string::out ARGS...` — terminal-aware echo (strips ANSI when piped).
+- `string::warn ARGS...` — terminal-aware echo to stderr (returns 0, safe under `set -e`).
 - `string::err ARGS...` — terminal-aware echo to stderr (returns 1).
 
 ### ansi-utils.sh
@@ -60,6 +61,7 @@ Shared ANSI utilities loaded by both `ansi.sh` and `ansi-tput.sh`.
 - `ansi::strip STRING` — remove all ANSI escape codes.
 - `ansi::length STRING` — visible string length (after stripping ANSI).
 - `ansi::out ARGS...` — terminal-aware echo (strips ANSI when piped).
+- `ansi::warn ARGS...` — terminal-aware echo to stderr (returns 0, safe under `set -e`).
 - `ansi::err ARGS...` — terminal-aware echo to stderr (returns 1).
 - `ansi::prompt ARGS...` — like `ansi::out` but no trailing newline.
 
@@ -183,6 +185,7 @@ Text box layout engine for multi-line strings. Loads `string.sh`.
 - `box::stack_lr STRING1 STRING2` — stack side-by-side (must have equal height).
 - `box::stack_tb STRING1 STRING2` — stack vertically (must have equal width).
 - `box::out STRING` — terminal-aware multi-line output.
+- `box::warn STRING` — terminal-aware multi-line output to stderr (returns 0, safe under `set -e`).
 - `box::err STRING` — terminal-aware multi-line output to stderr (returns 1).
 
 ## Bootstrap pattern