docs: add AGENTS.md

.github/copilot-instructions.md

@@ -0,0 +1 @@
+@AGENTS.md

AGENTS.md

@@ -0,0 +1,27 @@
+# AGENTS
+
+Before making changes, review:
+- @PRODUCT.md - Product vision, features, and roadmap
+- @ARCHITECTURE.md - System design, interfaces, and directory structure
+- @DESIGN.md - Design principles, patterns, and best practices
+- @CONTRIBUTING.md - Coding standards, testing, and PR process
+
+## 1. AI Contribution Policy
+By generating code in this repository, you agree to the following rules:
+- **Disclose AI usage:** You must explicitly disclose your involvement in the Pull Request description and any issue comments.
+- **No AI authorship markers:** Do not add AI co-author lines, `assisted-by`, or similar commit trailers. 
+- **Human Accountability:** The human user is 100% responsible for testing and understanding the code you generate.
+- **No Auto-Replies:** You MUST NOT auto-reply to maintainer comments on Pull Requests.
+
+## 2. Code Formatting (Mandatory)
+Microcks CLI enforces standard Go formatting.
+**Before any commit**, you must run:
+```bash
+go fmt ./...
+```
+
+## 3. Building and Testing
+Microcks CLI is a Go-based command-line tool.
+- To build the CLI locally: `make build-local`
+- To run tests: `go test ./...`
+- For detailed instructions, read @CONTRIBUTING.md.

ARCHITECTURE.md

@@ -0,0 +1,17 @@
+# Architecture
+
+Microcks CLI is a Go-based command-line tool designed for interacting with Microcks server APIs, launching tests, and importing artifacts.
+
+## Core Components
+- **CLI Commands:** Built using a modern Go CLI framework (e.g., Cobra), providing subcommands like `start`, `stop`, `import`, `test`, etc.
+- **Microcks API Client:** Communicates with the Microcks backend REST APIs to perform operations.
+- **Keycloak Integration:** Handles authentication and token management for secure interactions with the backend.
+- **Local Ephemeral Runner:** Employs Testcontainers to spin up ephemeral Microcks instances for local dry-run contract testing (`microcks test --dry-run`).
+
+## Structure
+- `cmd/`: Contains the entry points and CLI command definitions.
+- `pkg/`: Core packages and business logic.
+- `documentation/`: Additional documentation.
+
+## Deployment
+Available as a standalone binary for Linux, macOS, and Windows, and as a container image (`quay.io/microcks/microcks-cli`) for CI/CD integration.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

DESIGN.md

@@ -0,0 +1,16 @@
+# Design
+
+This document outlines the core design principles and patterns used in the Microcks CLI codebase.
+
+## Design Principles
+- **Simplicity:** The CLI should be easy to use with minimal dependencies, providing a straightforward developer experience.
+- **CI/CD Readiness:** Designed to be easily integrated into pipelines (GitHub Actions, Jenkins, Tekton) with machine-readable outputs (JSON, YAML, GitHub Actions).
+- **Graceful Error Handling:** Code under `pkg/` and `cmd/` must return errors using the internal `errors` package (e.g., `errors.Wrap(errors.KindConnection, err)`), never exiting or panicking arbitrarily.
+
+## Coding Standards
+- **Go Standard:** Strict adherence to idiomatic Go formatting (`go fmt`).
+- **Error Types:** Follow the guidelines in `documentation/error-handling.md` and use the specific exit codes (0-2 for standard, 11-20 for Microcks-specific).
+
+## Best Practices
+- **Modularity:** Keep command handlers thin and delegate business logic to packages in `pkg/`.
+- **Testability:** Provide dry-run options and use ephemeral test environments (Testcontainers) when necessary.

PRODUCT.md

@@ -0,0 +1,13 @@
+# Product
+
+## Vision
+Microcks CLI provides a simple and powerful command-line interface for the Microcks API Mocking and Testing platform. It empowers developers and CI/CD pipelines to interact with Microcks, deploy tests, and import artifacts with minimal overhead.
+
+## Key Features
+- **Pipeline Integration:** Native support for GitHub Actions, Tekton, and other CI/CD tools to trigger contract tests and API imports.
+- **Local Contract Testing:** Support for zero-infrastructure local testing via `microcks test --dry-run` and Testcontainers.
+- **Artifact Management:** Easily import API specifications (OpenAPI, AsyncAPI, Postman, etc.) from local directories or remote URLs.
+- **Machine-Readable Outputs:** Configurable output formats (JSON, YAML, GitHub Actions) for seamless integration with automation tools.
+
+## Roadmap
+Enhance the Developer Experience by providing deeper integrations with IDEs, supporting more complex testing scenarios, and continuously aligning with the features of the Microcks core platform.