Phase 4: Agent context, doctor command, CLAUDE.md, README

CLAUDE.md

@@ -0,0 +1,97 @@
+# CLAUDE.md - Development Context for Claude Code
+
+## Build and Run
+
+```bash
+# Install in development mode (editable)
+uv pip install -e ".[dev]"
+
+# Or install dependencies only
+uv sync
+
+# Run the CLI
+kbagent --help
+uv run kbagent --help
+
+# Run a specific command
+kbagent --json project list
+```
+
+## Testing
+
+```bash
+# Run all tests
+uv run pytest tests/ -v
+
+# Run a specific test file
+uv run pytest tests/test_cli.py -v
+
+# Run a specific test class or method
+uv run pytest tests/test_cli.py::TestProjectAdd -v
+uv run pytest tests/test_cli.py::TestProjectAdd::test_project_add_success_json -v
+```
+
+## Project Structure
+
+```
+src/keboola_agent_cli/
+  __init__.py           # __version__ = "0.1.0"
+  __main__.py           # python -m support
+  cli.py                # Typer root app, global options, subcommand wiring
+  client.py             # LAYER 3: HTTP client (only module talking to Keboola API)
+  config_store.py       # JSON persistence for config.json (0600 permissions)
+  models.py             # Pydantic models shared across layers
+  output.py             # OutputFormatter: JSON vs Rich dual-mode output
+  errors.py             # KeboolaApiError, ConfigError, mask_token()
+  commands/
+    project.py          # LAYER 1: CLI commands for project management
+    config.py           # LAYER 1: CLI commands for config browsing
+    context.py          # LAYER 1: Agent usage instructions
+    doctor.py           # LAYER 1: Health check command
+  services/
+    project_service.py  # LAYER 2: Business logic for projects
+    config_service.py   # LAYER 2: Business logic for configurations
+
+tests/
+  conftest.py           # Shared fixtures (tmp_config_dir, config_store, formatters)
+  test_cli.py           # End-to-end CLI tests via CliRunner
+  test_client.py        # API client tests with mocked HTTP
+  test_config_store.py  # Config persistence tests
+  test_errors.py        # mask_token() tests
+  test_models.py        # Pydantic model tests
+  test_output.py        # OutputFormatter tests
+  test_services.py      # Business logic tests
+```
+
+## Architecture: 3-Layer Design
+
+```
+CLI Commands (commands/)  -->  Services (services/)  -->  API Client (client.py)
+  Typer, output                 Business logic             HTTP, endpoints
+```
+
+- API changes: modify only `client.py`
+- Business logic changes: modify only `services/`
+- UI changes: modify only `commands/`
+
+## Coding Conventions
+
+1. **Typer commands** are thin - they parse arguments, call a service, and format output. No business logic in commands.
+
+2. **Services** receive `ConfigStore` and a `client_factory` callable via dependency injection. This enables easy testing with mocks.
+
+3. **All data models** use Pydantic 2.x (`BaseModel`). Models are defined in `models.py` and shared across layers.
+
+4. **Dual output**: every command supports `--json` for structured output and Rich formatting for human-readable output. Use `OutputFormatter.output(data, human_formatter)`.
+
+5. **Error handling**: commands catch `KeboolaApiError` and `ConfigError`, map them to the appropriate exit code, and output structured errors in JSON mode.
+
+6. **Exit codes**: 0=success, 1=general error, 2=usage error, 3=auth error, 4=network error, 5=config error.
+
+7. **Token masking**: tokens are never printed in full. Use `mask_token()` from `errors.py`.
+
+8. **Config file**: stored at `~/.config/keboola-agent-cli/config.json` with `0600` permissions. Managed by `ConfigStore`.
+
+9. **Tests**: use `typer.testing.CliRunner` for CLI tests, `unittest.mock` for mocking services and clients, `pytest` fixtures from `conftest.py`.
+
+10. **Dependencies**: typer, rich, httpx, pydantic, platformdirs. Dev: pytest, pytest-httpx.

README.md

@@ -1,3 +1,200 @@
-# Keboola Agent CLI
+# Keboola Agent CLI (`kbagent`)
 
-AI-friendly CLI for managing Keboola projects.
+AI-friendly CLI for managing Keboola projects. Designed for use by AI coding agents (Claude Code, Codex, Gemini) and human developers alike.
+
+## Features
+
+- **Multi-project management**: Connect to multiple Keboola projects across different stacks (AWS, Azure, GCP)
+- **Configuration browsing**: List and inspect extractors, writers, transformations, and applications
+- **Structured JSON output**: Every command supports `--json` for reliable programmatic parsing
+- **Health checks**: Built-in `doctor` command to verify setup and connectivity
+- **Agent context**: `kbagent context` provides comprehensive usage instructions for AI agents
+- **Secure token handling**: Tokens are stored with 0600 permissions and always masked in output
+
+## Installation
+
+```bash
+# Install with uv (recommended)
+uv tool install .
+
+# Or install in development mode
+uv pip install -e ".[dev]"
+```
+
+After installation, the `kbagent` command is available globally.
+
+## Quick Start
+
+```bash
+# 1. Add a Keboola project
+kbagent project add --alias prod --url https://connection.keboola.com --token YOUR_TOKEN
+
+# 2. Verify the connection
+kbagent project status
+
+# 3. List configurations
+kbagent config list
+
+# 4. Get structured JSON output (recommended for scripts and agents)
+kbagent --json config list
+```
+
+## Commands
+
+### Project Management
+
+```bash
+# Add a new project connection (token is verified against API)
+kbagent project add --alias NAME --url STACK_URL --token TOKEN
+
+# List all connected projects
+kbagent project list
+
+# Remove a project connection
+kbagent project remove --alias NAME
+
+# Edit an existing project (re-verifies token if changed)
+kbagent project edit --alias NAME [--url NEW_URL] [--token NEW_TOKEN]
+
+# Check connectivity to all projects (or a specific one)
+kbagent project status
+kbagent project status --project NAME
+```
+
+### Configuration Browsing
+
+```bash
+# List all configurations from all projects
+kbagent config list
+
+# Filter by project (can be repeated)
+kbagent config list --project prod
+kbagent config list --project prod --project dev
+
+# Filter by component type
+kbagent config list --component-type extractor
+
+# Filter by specific component
+kbagent config list --component-id keboola.ex-db-snowflake
+
+# Get full detail of a specific configuration
+kbagent config detail --project prod --component-id keboola.ex-db-snowflake --config-id 12345
+```
+
+### Utility Commands
+
+```bash
+# Show usage instructions for AI agents
+kbagent context
+
+# Run health checks (config, permissions, connectivity, version)
+kbagent doctor
+kbagent --json doctor
+```
+
+### Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--json` | `-j` | Output in JSON format for programmatic consumption |
+| `--verbose` | `-v` | Enable verbose output |
+| `--no-color` | | Disable colored Rich formatting |
+
+Non-TTY environments automatically disable Rich formatting.
+
+## JSON Output Format
+
+All commands with `--json` return a consistent structure.
+
+**Success:**
+```json
+{
+  "status": "ok",
+  "data": { ... }
+}
+```
+
+**Error:**
+```json
+{
+  "status": "error",
+  "error": {
+    "code": "INVALID_TOKEN",
+    "message": "Token is invalid or expired",
+    "project": "prod",
+    "retryable": false
+  }
+}
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Usage error (invalid arguments) |
+| 3 | Authentication error (invalid/expired token) |
+| 4 | Network error (timeout, unreachable server) |
+| 5 | Configuration error (corrupt config, unknown alias) |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `KBC_TOKEN` | Default Storage API token (used by `project add`) |
+| `KBC_STORAGE_API_URL` | Default stack URL (used by `project add`) |
+
+## Configuration
+
+Configuration is stored at `~/.config/keboola-agent-cli/config.json` with file permissions `0600` to protect stored tokens.
+
+```json
+{
+  "version": 1,
+  "default_project": "prod",
+  "projects": {
+    "prod": {
+      "stack_url": "https://connection.keboola.com",
+      "token": "901-...",
+      "project_name": "My Project",
+      "project_id": 1234
+    }
+  }
+}
+```
+
+## Architecture
+
+The project follows a 3-layer architecture:
+
+```
+CLI Commands (commands/)  -->  Services (services/)  -->  API Client (client.py)
+```
+
+- **Commands layer**: Thin Typer wrappers that parse arguments, call services, and format output
+- **Services layer**: Business logic, project resolution, multi-project aggregation
+- **Client layer**: HTTP communication with Keboola API, retry logic, error mapping
+
+## Development
+
+```bash
+# Install in development mode
+uv pip install -e ".[dev]"
+
+# Run tests
+uv run pytest tests/ -v
+
+# Run the CLI
+uv run kbagent --help
+```
+
+## Supported Keboola Stacks
+
+- AWS: `https://connection.keboola.com`
+- Azure (North Europe): `https://connection.north-europe.azure.keboola.com`
+- GCP (Europe West): `https://connection.europe-west3.gcp.keboola.com`
+
+## License
+
+MIT