@zigrivers/scaffold 3.6.0 → 3.8.0

package/content/knowledge/cli/cli-dev-environment.md

@@ -0,0 +1,121 @@
+---
+name: cli-dev-environment
+description: Local development setup for CLIs including npm link, cargo install, debug flags, manual testing workflow, and hot reload
+topics: [cli, dev-environment, npm-link, cargo, debug, hot-reload, testing-workflow]
+---
+
+CLI development has a tighter feedback loop requirement than library development: you need to run the actual binary, observe its output, and verify behavior against real filesystem and network state. Setting up a fast local development workflow is not optional — a slow iteration cycle compounds across hundreds of test invocations.
+
+## Summary
+
+CLI development requires a tight feedback loop: install locally via `npm link` (Node), `cargo install --path .` (Rust), or `pip install -e .` (Python), run the actual binary, and verify behavior. Support debug output via environment variables and `--verbose` flags, with debug output always on stderr to protect pipe chains.
+
+## Deep Guidance
+
+### Installing for Local Development
+
+**Node.js (npm link)**
+
+`npm link` creates a global symlink to the local package, making the CLI available as if installed globally:
+
+```bash
+cd my-cli
+npm install
+npm link          # Creates symlink in global node_modules
+my-cli --version  # Now resolves to local source
+```
+
+To unlink: `npm unlink my-cli` (run from the package directory).
+
+When using workspaces or monorepos, link from the workspace root and use the scoped package name.
+
+**Rust (cargo install --path)**
+
+```bash
+cargo install --path .    # Compiles and installs to ~/.cargo/bin/
+my-cli --version
+```
+
+During active development, prefer `cargo run -- <args>` to avoid reinstall overhead on each change.
+
+**Python (pip install -e)**
+
+```bash
+pip install -e .     # Editable install; changes reflect immediately
+my-cli --version
+```
+
+Editable installs are the Python equivalent of `npm link` — source changes are picked up without reinstall.
+
+**Go**
+
+```bash
+go install .         # Installs to $GOPATH/bin
+my-cli --version
+```
+
+Or run directly: `go run . <args>`.
+
+### Manual Testing Workflow
+
+Structure manual testing around scenarios, not individual flags:
+
+1. Define the happy path scenario as a shell script in `tests/manual/`
+2. Define common error scenarios (missing required arg, bad input format, network failure)
+3. Run the scenario script after each meaningful change
+
+Keep a `Makefile` target or `scripts/dev-test.sh` that runs the most important manual scenarios. This catches integration issues that unit tests miss and runs in seconds.
+
+### Debug Flags
+
+Support a debug output mode that is invisible in normal operation but invaluable during development:
+
+- **Node.js**: Respect `DEBUG=my-cli:*` using the `debug` package. Namespaced debug output appears only when the env var is set
+- **Rust**: Use `RUST_LOG=debug` with the `env_logger` or `tracing` crate
+- **Python**: `LOGLEVEL=DEBUG` with the `logging` module
+
+Add an explicit `--verbose` or `--debug` flag that mirrors the env var. This lets users report bugs with detailed output without requiring knowledge of the env var.
+
+Internal debug output always goes to stderr, never stdout. Stdout is for the tool's actual output; mixing diagnostic messages corrupts pipe chains.
+
+### Hot Reload for Node.js
+
+For TypeScript CLIs, use `ts-node` or `tsx` to avoid a compile step during development:
+
+```bash
+# Run directly with tsx (fast TypeScript runner)
+tsx src/index.ts <args>
+
+# Or use nodemon for file-watch rerun
+npx nodemon --ext ts --exec "tsx src/index.ts" -- <args>
+```
+
+Add a `dev` script to `package.json`:
+```json
+{
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js"
+  }
+}
+```
+
+### REPL Development
+
+When building interactive prompts or REPL-like features, test incrementally:
+
+- Mock `process.stdin` and `process.stdout` in unit tests to verify prompt sequences
+- Use `script` (Unix) or `Expect` to record and replay terminal interactions in integration tests
+- Test TTY vs non-TTY behavior explicitly — many prompt libraries silently skip prompts in non-TTY mode
+
+### Environment Isolation
+
+Use `.env.development` and `.env.test` files for environment-specific overrides. Never commit credentials. Load with `dotenv` (Node), `dotenvy` (Rust), or `python-dotenv`. Validate required env vars at startup with a clear error if missing.
+
+Isolate test runs from the user's real config by setting `XDG_CONFIG_HOME` and `HOME` to temporary directories in tests:
+
+```bash
+export XDG_CONFIG_HOME=$(mktemp -d)
+my-cli init  # reads/writes to temp dir, never touches ~/.config
+```

package/content/knowledge/cli/cli-distribution-patterns.md

@@ -0,0 +1,106 @@
+---
+name: cli-distribution-patterns
+description: npm, pip, and cargo publishing, Homebrew formulae, standalone binaries, Docker images, and GitHub Releases with checksums
+topics: [cli, distribution, npm, homebrew, cargo, pip, standalone-binaries, github-releases, checksums]
+---
+
+Distribution is where many CLI projects fail: the tool works perfectly in development but is painful to install, update, or run in different environments. A well-distributed CLI reaches users through multiple channels (package manager, direct download, container) and handles updates gracefully.
+
+## Summary
+
+A well-distributed CLI reaches users through multiple channels: package registries (npm, cargo, pip), Homebrew formulae, standalone binaries, and GitHub Releases with SHA256 checksums. Automate publishing via CI with trusted publishing (OIDC) rather than storing long-lived tokens. Notify users of updates asynchronously without blocking command execution.
+
+## Deep Guidance
+
+### Package Registry Publishing
+
+**npm (Node.js)**
+
+Declare `bin` in `package.json` and publish to npm:
+
+```json
+{
+  "name": "@myorg/my-cli",
+  "version": "1.0.0",
+  "bin": { "my-cli": "./bin/my-cli" },
+  "files": ["bin/", "dist/"]
+}
+```
+
+Users install with `npm install -g @myorg/my-cli`. Use `npm publish --access public` for scoped packages. Set up `publishConfig` for automated CI publishing via npm trusted publishing (GitHub OIDC) rather than storing long-lived tokens.
+
+**cargo (Rust)**
+
+Publish to crates.io with `cargo publish`. Users install with `cargo install my-cli`. Binary name is declared in `Cargo.toml` under `[[bin]]`. Provide pre-built binaries via GitHub Releases for users who do not have Rust installed.
+
+**pip (Python)**
+
+Use `pyproject.toml` with `[project.scripts]` to declare the CLI entry point. Publish to PyPI with `python -m build && twine upload`. Users install with `pip install my-cli` or `pipx install my-cli`. Prefer `pipx` for CLI tools — it installs in an isolated virtualenv, preventing dependency conflicts.
+
+### Homebrew Formulae
+
+Homebrew is the preferred installation channel for macOS users. Two options:
+
+**Core formula (homebrew-core)**: For widely-used tools. Submit a PR to `homebrew/homebrew-core`. Requires the tool to meet popularity and quality standards.
+
+**Custom tap**: For any tool, immediately available:
+
+```ruby
+# Formula/my-cli.rb
+class MyCli < Formula
+  desc "One-line description of what this does"
+  homepage "https://github.com/myorg/my-cli"
+  url "https://github.com/myorg/my-cli/archive/v1.0.0.tar.gz"
+  sha256 "abc123..."
+  license "MIT"
+
+  def install
+    bin.install "bin/my-cli"
+  end
+
+  test do
+    assert_match "1.0.0", shell_output("#{bin}/my-cli --version")
+  end
+end
+```
+
+Automate formula updates with `brew bump-formula-pr` or tools like `release-please`. The SHA256 in the formula must match the release tarball exactly.
+
+### Standalone Binaries
+
+Ship zero-dependency binaries for users who do not have the language runtime installed:
+
+- **Node.js**: `pkg` (Vercel) or `nexe` bundle Node + app into a single executable. `bun build --compile` produces a single binary. Provide binaries for `linux-x64`, `linux-arm64`, `darwin-x64`, `darwin-arm64`, `win-x64`
+- **Rust**: Cross-compile with `cross` (Docker-based cross-compiler). `cargo-dist` automates release binary creation and GitHub Release uploads
+- **Python**: `PyInstaller` bundles the interpreter and dependencies. `Nuitka` compiles to C for smaller binaries
+- **Go**: `GOOS=linux GOARCH=amd64 go build` — Go cross-compilation is built in
+
+### GitHub Releases with Checksums
+
+Every release should publish binaries with SHA256 checksums:
+
+```bash
+# Generate checksums
+sha256sum my-cli-linux-x64 my-cli-darwin-arm64 > checksums.txt
+
+# Upload to release
+gh release create v1.0.0 \
+  my-cli-linux-x64 \
+  my-cli-darwin-arm64 \
+  checksums.txt \
+  --title "v1.0.0" \
+  --notes-file CHANGELOG.md
+```
+
+Users verify: `sha256sum -c checksums.txt`. Homebrew formulae require a SHA256 of the source tarball. Provide a `checksums.txt` in a consistent, parseable format.
+
+### Auto-Update Strategy
+
+CLIs should notify users of available updates without blocking command execution:
+
+1. Check for updates asynchronously in a background process after command completes
+2. Cache the result for 24 hours to avoid hitting the registry on every run
+3. Print update notification to stderr so it does not corrupt stdout output
+4. Respect `--no-update-check` flag and `MYCLI_NO_UPDATE_CHECK` env var for CI environments
+
+Implement with a non-blocking background check: spawn a subprocess that writes the latest version to a cache file, then read that cache on the next invocation.

package/content/knowledge/cli/cli-interactivity-patterns.md

@@ -0,0 +1,116 @@
+---
+name: cli-interactivity-patterns
+description: Prompt libraries, spinners, progress bars, color output, TTY detection, and graceful degradation for piped output
+topics: [cli, interactivity, prompts, spinners, progress-bars, tty-detection, color, chalk]
+---
+
+Interactive CLI features — prompts, spinners, progress bars, colored output — exist to help humans. They must never obstruct machines. The guiding principle is graceful degradation: detect the execution context and silently disable interactive features when they would break automation.
+
+## Summary
+
+Interactive CLI features — prompts, spinners, progress bars, colored output — must be gated on TTY detection and degrade gracefully in pipes, redirected output, and CI environments. Always provide `--yes` / `--no-interactive` flags. Spinners and progress output go to stderr; data goes to stdout. Follow the `NO_COLOR` standard for color defeat.
+
+## Deep Guidance
+
+### TTY Detection
+
+Every interactive feature must be gated on TTY detection:
+
+```javascript
+// Node.js
+const isInteractive = process.stdout.isTTY && process.stdin.isTTY;
+```
+
+```rust
+// Rust
+use std::io::IsTerminal;
+let is_interactive = std::io::stdout().is_terminal();
+```
+
+```python
+# Python
+import sys
+is_interactive = sys.stdout.isatty()
+```
+
+Non-TTY contexts include: piped output (`my-cli | grep`), redirected output (`my-cli > out.txt`), CI environments (GitHub Actions, Jenkins), and SSH sessions without a pseudo-TTY. In these contexts: suppress spinners, suppress color, suppress prompts (or fail with a clear error if input is required).
+
+### Prompt Libraries
+
+For wizard-style input collection:
+
+- **Node.js**: `@inquirer/prompts` (modern, ESM, individual prompt imports), `prompts` (lightweight, no class hierarchy), `inquirer` (classic, comprehensive)
+- **Rust**: `dialoguer` (composable prompts: text, select, confirm, multi-select), `requestty`
+- **Python**: `questionary` (rich prompts), `click.prompt()` / `click.confirm()` (built into click)
+
+Prompt patterns:
+- **Text input**: Free-form string with optional validation and default
+- **Select**: Choose one from a list (arrow keys)
+- **Multi-select**: Choose multiple from a list (space to toggle)
+- **Confirm**: Yes/no boolean
+- **Password**: Hidden input (no echo)
+
+Always provide `--yes` / `--no-interactive` flags that skip prompts with defaults. In CI, any tool requiring interactive prompts without this escape hatch is broken.
+
+### Spinners
+
+Spinners indicate ongoing background work without a known duration:
+
+- **Node.js**: `ora` (most popular, customizable), `nanospinner` (tiny), `cli-spinners` (spinner frames only)
+- **Rust**: `indicatif` (spinners + progress bars)
+- **Python**: `halo`, `yaspin`
+
+Rules:
+- Only render spinners when `stdout.isTTY` is true
+- Spinners output to stderr, not stdout, so pipe chains are not polluted
+- Clear the spinner line before printing final output — users should not see spinner characters mixed with results
+- On completion, replace spinner with a final status line: `✓ Built in 2.4s`
+
+### Progress Bars
+
+Progress bars are appropriate when the total number of steps is known:
+
+```
+Building assets ████████████████░░░░ 80% (240/300 files)
+```
+
+- Show percentage, current/total count, and elapsed or estimated remaining time
+- Update at most 10–20 times per second — more frequent updates cause flicker without adding information
+- Collapse to a single completion line when done
+- For network transfers, show bytes downloaded and transfer rate
+
+### Color Output
+
+- **Node.js**: `chalk` (most popular), `picocolors` (tiny, fast), `kleur`
+- **Rust**: `colored`, `owo-colors`, `nu-ansi-term`
+- **Python**: `rich` (full formatting library), `colorama` (Windows ANSI compatibility), `termcolor`
+
+Color conventions:
+- **Green**: Success, completion
+- **Yellow/Amber**: Warning, deprecation
+- **Red**: Error, failure
+- **Cyan/Blue**: Informational, prompts
+- **Dim/Gray**: Secondary information, timestamps
+
+### Graceful Degradation Checklist
+
+Before shipping any interactive feature, verify it degrades correctly:
+
+```bash
+# Test pipe context
+my-cli build | cat
+
+# Test redirected output
+my-cli build > output.txt
+
+# Test CI simulation
+CI=true my-cli build
+
+# Test NO_COLOR
+NO_COLOR=1 my-cli build
+
+# Test non-interactive (should not hang waiting for input)
+echo "" | my-cli init
+```
+
+If any of these scenarios hangs, errors with formatting artifacts, or corrupts stdout with escape codes, the interactive feature is not correctly gated.

package/content/knowledge/cli/cli-output-patterns.md

@@ -0,0 +1,107 @@
+---
+name: cli-output-patterns
+description: --json/--format flags, table formatting, machine-readable output, piping conventions, and --quiet flag for CLI tools
+topics: [cli, output, json, formatting, tables, piping, stdout, stderr, machine-readable]
+---
+
+CLI output is a two-audience problem: humans reading in a terminal, and machines reading in a pipeline. Tools that ignore the machine audience force users to write fragile regex parsers against human-formatted output. Tools that ignore the human audience are inscrutable to debug. The solution is structured output modes with a clear default.
+
+## Summary
+
+CLI output serves two audiences: humans in terminals and machines in pipelines. stdout carries data; stderr carries status, progress, warnings, and errors. Provide `--json` for machine consumption, `--format` for multiple output modes, and `--quiet` to suppress non-error output. Use consistent snake_case field names in JSON output across all subcommands.
+
+## Deep Guidance
+
+### stdout vs stderr Convention
+
+This distinction is non-negotiable for tools expected to participate in pipelines:
+
+- **stdout**: The tool's result — data, transformed content, generated output. This is what `>` captures and `|` pipes.
+- **stderr**: Status messages, progress, warnings, errors — anything that is for the human operator, not the downstream process.
+
+```bash
+# Correct: status to stderr, data to stdout
+my-cli process input.json > output.json 2>errors.log
+
+# If status messages are on stdout, this breaks
+my-cli process input.json | jq '.result'   # jq sees status messages, fails to parse
+```
+
+Log every informational line, progress update, warning, and error to stderr. Reserve stdout for the tool's actual data output.
+
+### --json Flag
+
+Provide `--json` for any command that produces output a script might consume:
+
+```bash
+my-cli status --json
+# Output:
+{
+  "status": "running",
+  "pid": 12345,
+  "uptime": 3600,
+  "version": "2.4.1"
+}
+```
+
+Rules for `--json` output:
+- Always valid JSON — never mix human-readable text with JSON
+- Always exit 0 and include an error field for operational errors, rather than outputting JSON to stdout and error text to stdout
+- For errors: `{"error": "message", "code": "ERROR_CODE"}` to stderr with non-zero exit
+- Arrays for lists, never newline-separated JSON objects (unless using JSON Lines)
+
+**JSON Lines** (`--json-lines` or `--format=jsonl`): For streaming or large list output, emit one JSON object per line. Each line is independently parseable. This is preferred over wrapping everything in a single JSON array when the output can be large.
+
+### --format Flag
+
+For tools that support multiple output formats:
+
+```bash
+my-cli list --format=table    # Human-readable table (default)
+my-cli list --format=json     # JSON array
+my-cli list --format=csv      # CSV with header row
+my-cli list --format=tsv      # Tab-separated, no header (script-friendly)
+```
+
+When `--format` is provided without a value, default to `json`. When piping to a non-TTY, consider defaulting to `json` automatically.
+
+### Table Formatting
+
+For human-readable tabular output:
+
+- **Node.js**: `columnify`, `cli-table3`, `tabled`
+- **Rust**: `comfy-table`, `prettytable-rs`, `tabled`
+- **Python**: `tabulate`, `rich.table`
+
+Table rules:
+- Align columns consistently; numbers right-aligned, strings left-aligned
+- Truncate long values with `...` suffix to preserve column alignment
+- Print column headers by default; suppress with `--no-header`
+- Respect terminal width (`process.stdout.columns`) — do not print lines that wrap unexpectedly
+
+### --quiet Flag
+
+`--quiet` / `-q` suppresses all non-error output. The tool runs silently and only prints to stderr if something goes wrong:
+
+```bash
+my-cli build --quiet && echo "Build OK"  # Only "Build OK" appears on success
+```
+
+Quiet mode is essential for cron jobs, shell scripts that run in the background, and CI steps where unrelated output creates noise.
+
+Quiet + --json interaction: `--json` takes precedence. A user who explicitly requests JSON output expects it even with `--quiet`.
+
+### Output Format Decision Matrix
+
+| Scenario | Recommended Format |
+|---|---|
+| Interactive terminal, human operator | Table or formatted text |
+| Piped to another CLI tool | JSON or TSV |
+| CI/CD logging | Plain text (no ANSI), or JSON Lines |
+| Consumed by a script | JSON with `--json` |
+| Large dataset (streaming) | JSON Lines |
+| Copy-paste into a document | Plain text or CSV |
+
+### Consistent Field Names
+
+When outputting JSON, use consistent snake_case field names across all subcommands. Define a schema. Breaking changes to JSON output are breaking changes to any script that consumes the tool — treat them with the same care as a library API change.

package/content/knowledge/cli/cli-project-structure.md

@@ -0,0 +1,124 @@
+---
+name: cli-project-structure
+description: Directory layout, entry points, config file resolution, and plugin directory structure for CLI projects
+topics: [cli, project-structure, directory-layout, config-resolution, bin, plugins]
+---
+
+A well-structured CLI project makes it easy to add subcommands, locate business logic, and onboard contributors. The structure should reflect the mental model of the tool: commands are the public API, utilities are shared infrastructure, and configuration drives runtime behavior.
+
+## Summary
+
+A CLI project structure separates concerns into `bin/` (entry point), `src/commands/` (one file per subcommand), `src/utils/` (shared business logic), and `tests/`. Command handlers are thin dispatchers; business logic belongs in utilities. Config files are discovered in precedence order from CLI flags through project-local files to XDG Base Directory user config.
+
+## Deep Guidance
+
+### Canonical Directory Layout
+
+```
+my-cli/
+├── bin/
+│   └── my-cli          # Entry point (Node shebang or compiled binary symlink)
+├── src/
+│   ├── commands/       # One file per subcommand
+│   │   ├── init.ts
+│   │   ├── build.ts
+│   │   └── deploy.ts
+│   ├── utils/          # Shared helpers (not command-specific)
+│   │   ├── logger.ts
+│   │   ├── config.ts
+│   │   └── fs.ts
+│   ├── types/          # Shared type definitions
+│   └── index.ts        # CLI entry point (parses argv, routes to commands)
+├── tests/
+│   ├── commands/       # Integration tests per command
+│   └── utils/          # Unit tests for utilities
+├── package.json        # (Node) or Cargo.toml (Rust) or pyproject.toml (Python)
+└── README.md
+```
+
+### Command File Convention
+
+Each command file owns one subcommand and should export:
+- A `command` descriptor (name, aliases, description, flags schema)
+- A `handler` function that receives parsed arguments and executes the operation
+
+Keep handler functions thin: validate inputs, call service functions from `utils/`, handle errors, format output. Business logic belongs in `utils/`, not in command handlers.
+
+### bin/ Entry Point
+
+The `bin/` entry point is what users run. It should:
+1. Set up the Node/Python/Rust runtime minimum (e.g., `#!/usr/bin/env node`)
+2. Import and invoke the CLI router from `src/index.ts`
+3. Contain no business logic
+
+For Node.js, declare the bin in `package.json`:
+```json
+{
+  "bin": {
+    "my-cli": "./bin/my-cli"
+  }
+}
+```
+
+For compiled languages (Rust, Go), `bin/` may contain the compiled binary or a wrapper script. The real entry point is `src/main.rs` or `cmd/root.go`.
+
+### Config File Resolution
+
+Config files should be discovered in order from most-specific to most-general:
+
+1. Path from `--config` flag (explicit override)
+2. `MYCLI_CONFIG` environment variable
+3. `./mycli.config.json` (project-local, in current working directory)
+4. `.myclirc` (project-local dotfile)
+5. `~/.config/mycli/config.json` (XDG Base Directory standard)
+6. `~/.myclirc` (legacy home dotfile)
+7. Built-in defaults
+
+Use XDG Base Directory (`~/.config/<name>/`) as the preferred user config location on Linux/macOS. On Windows, use `%APPDATA%\<name>\config.json`. Libraries like `env-paths` (Node) or the `dirs` crate (Rust) handle cross-platform config paths correctly.
+
+Walk the directory tree upward from CWD when looking for project-local config (same pattern as `.gitignore`). Stop at the home directory or filesystem root.
+
+### Plugin Directory Structure
+
+If the tool supports plugins:
+
+```
+~/.config/mycli/
+├── config.json         # User config
+└── plugins/
+    ├── my-plugin/
+    │   ├── package.json
+    │   └── index.js
+    └── another-plugin/
+        └── ...
+```
+
+Plugin discovery scans `~/.config/mycli/plugins/` at startup. Each plugin directory must have a manifest (`package.json` or `plugin.json`) declaring:
+- `name`: Plugin identifier
+- `version`: Semver
+- `main`: Entry point relative to plugin directory
+- `commands`: Array of subcommand names the plugin registers
+
+### Monorepo CLI Structure
+
+When a CLI is part of a larger monorepo:
+
+```
+packages/
+├── cli/                # The CLI package
+│   ├── src/commands/
+│   └── package.json
+├── core/               # Shared business logic (used by CLI + SDK + server)
+└── sdk/                # Programmatic API (no CLI dependency)
+```
+
+Keep the CLI package thin. Business logic in `core/` can be tested without CLI overhead and reused by other consumers. The CLI is a delivery mechanism, not the application.
+
+### State File Convention
+
+Runtime state (auth tokens, cached data, last-run timestamps) should be stored separately from config:
+
+- Config: user-editable settings (`~/.config/mycli/config.json`)
+- State: machine-managed runtime data (`~/.local/share/mycli/state.json` per XDG, or `~/.mycli/state.json`)
+
+Never overwrite user config with machine-managed state. Mixing them causes painful merge conflicts and makes it hard to commit config to a dotfiles repo.

package/content/knowledge/cli/cli-requirements.md

@@ -0,0 +1,101 @@
+---
+name: cli-requirements
+description: CLI UX principles, POSIX conventions, exit codes, signal handling, and progressive disclosure for command-line tools
+topics: [cli, ux, posix, exit-codes, signal-handling, progressive-disclosure]
+---
+
+CLI tools occupy a unique design space: they are used by humans typing commands, embedded in shell scripts, and piped together in pipelines. A tool that conflates these contexts fails at all of them. The guiding principle is: do one thing well, fail loudly with actionable errors, and never surprise the pipeline.
+
+## Summary
+
+CLI tools serve humans, shell scripts, and pipelines simultaneously. Follow POSIX flag conventions, use standard exit codes (0 success, 1 error, 2 usage), handle signals cleanly (SIGINT, SIGTERM, SIGPIPE), and implement progressive disclosure in help output. Define the tool's single responsibility before writing code.
+
+## Deep Guidance
+
+### Do One Thing Well
+
+Unix philosophy is not aspirational — it is a load-bearing constraint. A CLI that tries to be a GUI, an interactive REPL, and a batch processor will be worse than a dedicated tool at each. Define the single responsibility before writing a line of code: what is the one transformation or action this tool performs?
+
+Corollaries:
+- Subcommands are fine; each subcommand should still do one thing
+- Options should modify behavior, not switch into a different tool
+- If two features feel unrelated, they probably belong in two tools connected by a pipe
+
+### POSIX Conventions
+
+Following POSIX conventions is not optional for tools that expect to live in shell scripts. Deviating breaks the mental model of every experienced shell user:
+
+- Short flags use a single dash and one letter: `-v`, `-q`, `-n`
+- Long flags use double dash: `--verbose`, `--quiet`, `--dry-run`
+- Short flags can be combined: `-vq` is equivalent to `-v -q`
+- Flags precede positional arguments; `--` terminates flag parsing
+- Options that take values: `-o output.txt` or `--output=output.txt`
+- Mutually exclusive flags should be documented, not silently overridden
+
+### Exit Codes
+
+Exit codes are the API surface of a CLI. Scripts depend on them; violating the convention silently breaks downstream automation:
+
+- **0** — success, operation completed as expected
+- **1** — general error (operation failed for a known reason)
+- **2** — usage error (bad arguments, missing required flag, unknown subcommand)
+- **126** — command found but not executable
+- **127** — command not found
+- **130** — terminated by Ctrl-C (128 + SIGINT signal 2)
+
+Always exit with 1 for domain errors, 2 for argument errors. Never exit 0 when something went wrong. Scripts using `set -e` will silently swallow partial failures if a tool exits 0 on error.
+
+### Signal Handling
+
+Respect signals — scripts set `trap` handlers and expect clean shutdown:
+
+- **SIGINT** (Ctrl-C): Interrupt. Clean up temp files, restore terminal state (if using raw mode), then exit 130
+- **SIGTERM**: Graceful shutdown request. Same cleanup as SIGINT; exit 143 (128 + 15)
+- **SIGPIPE**: Write to a closed pipe (e.g., `mytool | head -5` closes stdin after 5 lines). Handle by exiting cleanly rather than printing a broken pipe error
+
+Register signal handlers at startup. In Node.js: `process.on('SIGINT', cleanup)`. In Rust: the `ctrlc` crate. In Python: `signal.signal(signal.SIGINT, handler)`.
+
+### Progressive Disclosure
+
+Help output should scale with user familiarity:
+
+- `--help` shows the most common options and a one-line description of each
+- `--help --verbose` or `help <subcommand>` shows full option documentation
+- Man pages contain full reference material including examples and edge cases
+- Error messages should name the bad input and suggest the fix: `Unknown flag --colour. Did you mean --color?`
+
+Never dump 200 lines of option documentation in response to a bad argument. The user who mistyped a flag wants a correction, not a manual.
+
+### Input Validation Order
+
+Validate in this order to give the most useful errors earliest:
+
+1. Flag syntax (unknown flags, missing required values)
+2. Required argument presence
+3. Type/format validation (is this a valid integer? a valid path?)
+4. Semantic validation (does the file exist? does the user have permission?)
+5. External resource validation (can we reach the API? is the DB up?)
+
+Exit 2 for steps 1–3 (usage errors). Exit 1 for steps 4–5 (runtime errors).
+
+### Stdin / Stdout Pipeline Contract
+
+A tool that participates in pipelines must honor these contracts:
+
+- **Accept stdin**: If the tool reads input, accept it from stdin when no file argument is provided. `my-cli process < input.txt` and `cat input.txt | my-cli process` must both work.
+- **Write to stdout**: All output data goes to stdout. All status, progress, and error messages go to stderr. Violating this breaks every pipe chain the tool participates in.
+- **Exit on broken pipe**: When the downstream process closes its stdin (e.g., `my-cli list | head -5`), the tool receives SIGPIPE. Handle it cleanly — do not print a "broken pipe" error.
+- **No color in pipes**: When stdout is not a TTY, disable ANSI color codes automatically. Colored output in a pipe corrupts the downstream process's input.
+- **No interactive prompts in pipes**: When stdin is not a TTY, never prompt for user input. Either use defaults or fail with a clear error requesting the `--yes` flag.
+
+### Error Message Quality
+
+Error messages are the primary user support channel for CLI tools. Every error should answer three questions:
+
+1. **What happened?** — "Could not connect to the API at https://api.example.com"
+2. **Why did it happen?** — "Connection timed out after 10 seconds"
+3. **What should the user do?** — "Check your network connection, or set --timeout to increase the timeout"
+
+Never print a raw stack trace to the user. Stack traces go to debug output or log files. The user-facing message should be actionable. For unknown errors, provide a way to capture debug output: "Run with --verbose and file an issue at https://github.com/..."
+
+Suggest corrections for common mistakes: `Unknown command 'biuld'. Did you mean 'build'?` Use Levenshtein distance or a fuzzy matching library to find close matches among known commands and flags.