chaliy · chaliy · Jan 10, 2026 · Jan 10, 2026 · Jan 10, 2026 · Jan 10, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -15,11 +15,13 @@ Critical Thinking Fix root cause (not band-aid). Unsure: read more code; if stil
 
 ## Top level requirements
 
-- CLI tool for generating textual artifacts using LLM
+- Coding Agent friendly tool to magically generate text and images
+- CLI for generating textual and visual artifacts using LLM
 - Minimal self-contained OpenAI provider (no external LLM libraries)
 - Supports Jinja2-like template variables in prompts
 - Model selection and reasoning level configuration
-- Designed for CI/CD integration
+- Designed for CI/CD integration and AI agent workflows
+- Rich error messages with recovery hints for agent self-correction
 
 ## Local dev expectations
 
@@ -74,6 +76,7 @@ CI is implemented using GitHub Actions (`.github/workflows/ci.yaml`):
 4. Build: Ensure `cargo build` succeeds
 5. Full help: If CLI options changed, update `print_full_help()` in `src/main.rs`
 6. Lockfile: Run `cargo update --workspace` after version bumps or dependency changes to sync Cargo.lock
+7. README: If README needs changes, update `prompts/trickery_readme.md` and regenerate with `trickery generate ./prompts/trickery_readme.md > README.md`
 
 ## Commit message conventions
 
@@ -120,6 +123,7 @@ High-level approach.
 
 Available specs:
 
+- `coding-agent-design.md` - Agent-friendly design principles, error recovery, discoverability
 - `llm-provider.md` - LLM provider abstraction, OpenAI integration, design choices
 - `text-input.md` - Direct text input via --text option, alternative to file input
 

diff --git a/README.md b/README.md
@@ -1,10 +1,16 @@
-# Magic tool to generate things
+# Trickery
+
+Coding Agent friendly tool to magically generate text and images.
+
+[![CI](https://github.com/chaliy/trickery/actions/workflows/ci.yaml/badge.svg)](https://github.com/chaliy/trickery/actions/workflows/ci.yaml)
+[![Crates.io](https://img.shields.io/crates/v/trickery)](https://crates.io/crates/trickery)
+[![Coding Agent Friendly](https://img.shields.io/badge/coding%20agent-friendly-brightgreen)](specs/coding-agent-design.md)
 
 [![Stand With Ukraine](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner2-direct.svg)](https://vshymanskyy.github.io/StandWithUkraine/)
 
-cli to generate textual artifacts using LLM.
+CLI for generating textual and visual artifacts using LLM. Designed for CI/CD pipelines and AI coding agents.
 
-Idea is simple, imagine you need to generate some docs using LLM as part of CI, this is a tool for you.
+Idea is simple: need to generate docs, images, or other artifacts as part of CI? This tool integrates seamlessly into scripts and agent workflows.
 
 > [!TIP]
 > This README was generated with trickery
@@ -48,6 +54,17 @@ Input file could be any text file, with Jinja2-like template variables, like `{{
 - [Input Images](docs/input-images.md) - Using images in multimodal prompts
 - [Image Generation](docs/image-generation.md) - Generating and editing images
 
+## Agent-Friendly Design
+
+Trickery is built with AI coding agents in mind:
+
+- **Rich error messages** - Errors include context and recovery hints, so agents can self-correct
+- **Full help system** - Run `trickery help --full` for comprehensive documentation with examples
+- **Predictable output** - Use `--json` for structured output that's easy to parse
+- **Template variables** - Reproducible prompts with `{{ variable }}` substitution
+- **Auto-detection** - Input can be file path or direct text, no flags needed
+- **Exit codes** - Proper exit codes for script/agent error handling
+
 ## Українською 🇺🇦
 
 Trickery — невеликий інструмент командного рядка для автоматичної генерації текстових артефактів за допомогою великих мовних моделей. Ідея проста: якщо вам потрібно генерувати документацію, звіти або інші тексти в рамках CI/CD, цей інструмент допоможе інтегрувати виклики LLM у ваші скрипти та конвеєри. Доступні варіанти підстановки змінних у шаблонах, можливість роботи з мультимодальними підказками та простий інтерфейс для інтеграції в існуючі процеси.

diff --git a/prompts/trickery_readme.md b/prompts/trickery_readme.md
@@ -1,4 +1,4 @@
-You are helping to maintain repository with `trickery` tool, which is "Magic tool to generate things"
+You are helping to maintain repository with `trickery` tool, which is "Coding Agent friendly tool to magically generate text and images"
 
 Please generate a README.md using template below.
 
@@ -8,14 +8,19 @@ Please generate a README.md using template below.
 
 << TEMPLATE START >>
 
-# Magic tool to generate things
+# Trickery
 
-[![Stand With Ukraine](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner2-direct.svg)](https://vshymanskyy.github.io/StandWithUkraine/)
+Coding Agent friendly tool to magically generate text and images.
+
+[![CI](https://github.com/chaliy/trickery/actions/workflows/ci.yaml/badge.svg)](https://github.com/chaliy/trickery/actions/workflows/ci.yaml)
+[![Crates.io](https://img.shields.io/crates/v/trickery)](https://crates.io/crates/trickery)
+[![Coding Agent Friendly](https://img.shields.io/badge/coding%20agent-friendly-brightgreen)](specs/coding-agent-design.md)
 
+[![Stand With Ukraine](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner2-direct.svg)](https://vshymanskyy.github.io/StandWithUkraine/)
 
-cli to generate textual artifacts using LLM.
+CLI for generating textual and visual artifacts using LLM. Designed for CI/CD pipelines and AI coding agents.
 
-Idea is simple, imagine you need to generate some docs using LLM as part of CI, this is a tool for you.
+Idea is simple: need to generate docs, images, or other artifacts as part of CI? This tool integrates seamlessly into scripts and agent workflows.
 
 > [!TIP]
 > This README was generated with trickery
@@ -49,6 +54,17 @@ Input file could be any text file, with Jinja2-like template variables, like `{{
 - [Input Images](docs/input-images.md) - Using images in multimodal prompts
 - [Image Generation](docs/image-generation.md) - Generating and editing images
 
+## Agent-Friendly Design
+
+Trickery is built with AI coding agents in mind:
+
+- **Rich error messages** - Errors include context and recovery hints, so agents can self-correct
+- **Full help system** - Run `trickery help --full` for comprehensive documentation with examples
+- **Predictable output** - Use `--json` for structured output that's easy to parse
+- **Template variables** - Reproducible prompts with `{{ variable }}` substitution
+- **Auto-detection** - Input can be file path or direct text, no flags needed
+- **Exit codes** - Proper exit codes for script/agent error handling
+
 ## Українською 🇺🇦
 
 < Опис цього проекта українською >

diff --git a/specs/coding-agent-design.md b/specs/coding-agent-design.md
@@ -0,0 +1,87 @@
+# Coding Agent Design
+
+## Abstract
+
+Trickery is designed to be friendly for AI coding agents (Claude, GPT, Copilot, etc.) that need to generate text and images as part of automated workflows. The tool prioritizes discoverability, predictable behavior, and actionable error messages that enable agents to self-correct.
+
+## Requirements
+
+### Discoverability
+
+1. **Full help system** - `trickery help --full` outputs comprehensive documentation with examples, similar to llms.txt format
+2. **Command help** - Each command supports `--help` with usage patterns
+3. **Shell completions** - `trickery completion <shell>` for bash, zsh, fish, elvish, powershell
+
+### Error Recovery
+
+Errors must include enough context for an agent to understand what went wrong and how to fix it.
+
+1. **Missing API key** - Shows which env var to set and where to get a key
+2. **Network errors** - Distinguishes connection vs timeout, suggests retry
+3. **API errors** - Includes status code and hints for common codes (401, 429, 500)
+4. **File errors** - Explains permission issues, suggests path corrections
+5. **Exit codes** - Non-zero exit for errors, zero for success
+
+Example error output:
+```
+🔑 Missing API Key: OPENAI_API_KEY
+
+ℹ To fix this, set the environment variable:
+
+   export OPENAI_API_KEY=your_api_key_here
+
+ℹ You can get an API key from: https://platform.openai.com/api-keys
+```
+
+### Predictable Behavior
+
+1. **Structured output** - `--json` flag outputs machine-readable JSON
+2. **Auto-detection** - Input can be file path or direct text, determined automatically
+3. **Template variables** - `{{ var }}` syntax with `-v key=value` for reproducible prompts
+4. **Consistent flags** - Same flags work across commands where applicable
+
+### CI/CD Integration
+
+1. **No interactive prompts** - All input via arguments or stdin
+2. **Environment variables** - API keys and base URL via env vars
+3. **Exit codes** - Proper exit codes for scripting
+4. **Quiet mode** - Minimal output for piping (`generate` outputs only LLM response)
+
+## Design Choices
+
+### Why detailed error messages?
+
+Agents parse error output to decide next steps. Cryptic errors like "request failed" force guessing. Rich errors with hints ("API key invalid, get one at...") let agents suggest fixes or retry with corrections.
+
+### Why auto-detect file vs text input?
+
+Agents often construct prompts dynamically. Requiring explicit `--file` vs `--text` flags adds friction. Auto-detection (check if path exists) handles both cases naturally:
+
+```bash
+# Agent can do either:
+trickery generate prompts/template.md
+trickery generate "Write a haiku about $TOPIC"
+```
+
+### Why template variables instead of string interpolation?
+
+Shell interpolation happens before trickery sees the input, making debugging hard. Template variables (`{{ var }}`) are processed by trickery, visible in the template file, and explicit via `-v` flags.
+
+### Why JSON output option?
+
+Agents parsing natural text is error-prone. `--json` provides structured output:
+
+```json
+{
+  "content": "Generated text here...",
+  "model": "gpt-5-mini",
+  "usage": {"prompt_tokens": 10, "completion_tokens": 50}
+}
+```
+
+## Implementation Notes
+
+- Error formatting: `src/error.rs` - icons, hints, and structured messages
+- Help system: `src/main.rs` `print_full_help()` - comprehensive examples
+- Auto-detection: `src/commands/generate.rs` - file existence check
+- JSON output: `src/output.rs` - serde serialization