# CLI Architecture & Interface Coding Standards

> **Scope:** Applies to all shell scripts, CLI utilities, and UI libraries within this repository.  
> **Target Audience:** Human Developers & AI Coding Agents.

---

## 1. Core Principles

1. **Separation of Concerns:** UI layout modules (`ui.sh`) must contain strictly presentation logic. Application business logic belongs exclusively in application scripts (`app.sh`).
2. **Standard Compliance:** All CLI flags, environment variables, and stream outputs must strictly follow POSIX/GNU conventions and terminal specs (e.g., [no-color.org](https://no-color.org)).
3. **High Contrast First:** Visual themes must remain fully legible across dark, bright, blue, or transparent terminal backgrounds. Low-contrast default colors (e.g., standard dark blue `\033[34m`) are strictly prohibited.
4. **Resilient Option Parsing:** All `printf` calls rendering variable data or dynamic titles MUST use the option terminator (`printf --`) to prevent leading hyphens from being interpreted as command flags.

---

## 2. Standard CLI Flags & Environment Variables

All application scripts accepting command-line flags MUST implement the following reference matrix using normalized kebab-case.

| Flag (Long) | Flag (Short) | Env Variable | Behavior / Requirement |
| :--- | :--- | :--- | :--- |
| `--no-color`<br>`--no-colors` | *-* | `NO_COLOR=1`<br>`USE_COLOR=false` | Strips all ANSI escape sequences. Outputs plain text. |
| `--no-icon`<br>`--no-icons` | *-* | `NO_ICONS=1`<br>`USE_ICONS=false` | Strips or suppresses multi-byte Unicode emojis and glyphs. |
| `--plain` | *-* | *-* | Convenience flag equivalent to `--no-color --no-icons`. |
| `--yes` | `-y` | `ASSUME_YES=1` | Non-interactive mode. Bypasses prompt confirmations. |
| `--dry-run` | *-* | `DRY_RUN=1` | Simulates destructive operations without mutating system state. |
| `--verbose` | `-v` | `VERBOSE=1` | Prints diagnostic logs to `stderr`. |
| `--quiet` | `-q` | `QUIET=1` | Suppresses headers and non-essential UI stream outputs. |
| `--help` | `-h` | *-* | Prints usage information to `stdout` and exits with code `0`. |
| `--version` | `-V` | *-* | Prints application version string to `stdout` and exits with code `0`. |

---

## 3. UI Library Sourcing & Fallback Resolution

Application entry points (`app.sh`) MUST resolve UI dependencies dynamically across environment paths before crashing.

```bash
# Sourcing Resolution Sequence
LBIN_PATH="$HOME/lbin/ui.sh"
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
LOCAL_PATH="$SCRIPT_DIR/ui.sh"

if [ -f "$LBIN_PATH" ]; then
    TARGET_UI="$LBIN_PATH"
elif [ -f "$LOCAL_PATH" ]; then
    TARGET_UI="$LOCAL_PATH"
else
    echo "Error: Required UI library 'ui.sh' not found." >&2
    exit 1
fi

# Pass all CLI flags directly into the library initializer
source "$TARGET_UI" "$@"