@gluecharm-lab/easyspecs-cli 0.0.11 → 0.0.12

package/README.md

@@ -61,6 +61,20 @@ easyspecs-cli diagnose coordination-duplicates --cwd /your/repo --ci --json
 
 Run **`easyspecs-cli help`** for the full command tree. This README does not duplicate every flag; the built-in help matches the installed package version.
 
+## Terminal diagnostics (colors)
+
+Long-running commands (**`run synthesis`**, **`analysis`**, **`diagnose`** with **`--verbose`**, etc.) print **structured lines** on stderr with bracket prefixes such as **`[pool]`**, **`[queue]`**, **`[setup]`**, **`[AgentCode]`**, **`[context]`**, **`[index]`** — same vocabulary as the EasySpecs Analysis output in VS Code. Logs say **AgentCode** for the agent subprocess; the executable on your machine may still be **`opencode`** on **`PATH`**.
+
+When **stderr** is an interactive **TTY**, those prefixes are **colorized** (ANSI) for faster scanning.
+
+| Mechanism | Effect |
+| --------- | ------ |
+| **`NO_COLOR`** set to any non-empty value | Colors **disabled** ([no-color.org](https://no-color.org/)). |
+| **`FORCE_COLOR`** set to any non-empty value | Colors **allowed** even if stderr is **not** a TTY (e.g. piping to **`tee`**). |
+| **`--json`** | Normal runs **suppress** stderr diagnostics; stderr never receives ANSI in that mode so JSON on stdout stays machine-safe. With **`--json --verbose`**, stderr lines are **plain text** (no ANSI). |
+
+**Behaviour:** bracket tags are colorized; **`[pool]`** lines bold the work-item id and dim **`(active n/m)`**; **`[AgentCode]`** lines dim **`prompt` / `command` / `cwd` / `argv`** labels; multi-line **`stderr`/`stdout`** dumps are indented and dimmed; **blank lines** appear when the phase family changes (e.g. **`[setup]`** → **`[pool]`**, **`[pool]`** → **`[AgentCode]`**). Purely visual — message text is unchanged for grep.
+
 ## Configuration
 
 Primary configuration file: **`<repo>/.easyspecs/config.json`** (auto-created when needed, except for **`help`**, **`version`**, and **`doctor`** which do not create the file on first run). **`auth login --email … --password …`** stores tokens for upload commands (optional **`--session-path`** on the command tail updates **`easyspecs.cliSessionPath`** in **`config.json`**).

package/commands.md

@@ -28,6 +28,8 @@ These flags may appear **before** the subcommand. Anything after the first non-f
 | `--version`, `-V` | Print CLI package version (also `version` as first positional). Does **not** create config. |
 | `--config <path>` | Parsed but **unused** by `main.ts` today; configuration is read from `<repoRoot>/.easyspecs/config.json`. |
 
+Environment (stderr styling): **`NO_COLOR`** (any non-empty value) disables ANSI colors. **`FORCE_COLOR`** (any non-empty value) allows colors even when stderr is not a TTY. With **`--json`**, human stderr is normally suppressed; **`--json --verbose`** prints plain stderr **without** ANSI. In human mode, a **blank line** may be printed when the diagnostic **phase** changes (e.g. **`[setup]`** → **`[pool]`** / **`[AgentCode]`**). See **README** (Terminal diagnostics).
+
 ---
 
 ## Shared configuration (SRS-43)