add AGENTS.md and also updated API documentation

Author: harshavardhana

AGENTS.md

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

CLAUDE.md

@@ -0,0 +1,110 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+### Testing
+```bash
+# Run all tests with race detection (requires MinIO server at localhost:9000)
+SERVER_ENDPOINT=localhost:9000 ACCESS_KEY=minioadmin SECRET_KEY=minioadmin ENABLE_HTTPS=1 MINT_MODE=full go test -race -v ./...
+
+# Run tests without race detection
+go test ./...
+
+# Run short tests only (no functional tests)
+go test -short -race ./...
+
+# Run functional tests
+go build -race functional_tests.go
+SERVER_ENDPOINT=localhost:9000 ACCESS_KEY=minioadmin SECRET_KEY=minioadmin ENABLE_HTTPS=1 MINT_MODE=full ./functional_tests
+
+# Run functional tests without TLS
+SERVER_ENDPOINT=localhost:9000 ACCESS_KEY=minioadmin SECRET_KEY=minioadmin ENABLE_HTTPS=0 MINT_MODE=full ./functional_tests
+```
+
+### Linting and Code Quality
+```bash
+# Run all checks (lint, vet, test, examples, functional tests)
+make checks
+
+# Run linter only
+make lint
+
+# Run vet and staticcheck
+make vet
+
+# Alternative: run golangci-lint directly
+golangci-lint run --timeout=5m --config ./.golangci.yml
+```
+
+### Building Examples
+```bash
+# Build all examples
+make examples
+
+# Build a specific example
+cd examples/s3 && go build -mod=mod putobject.go
+```
+
+## Architecture
+
+### Core Client Structure
+The MinIO Go SDK is organized around a central `Client` struct (api.go:52) that implements Amazon S3 compatible methods. Key architectural patterns:
+
+1. **Modular API Organization**: API methods are split into logical files:
+   - `api-bucket-*.go`: Bucket operations (lifecycle, encryption, versioning, etc.)
+   - `api-object-*.go`: Object operations (legal hold, retention, tagging, etc.)
+   - `api-get-*.go`, `api-put-*.go`: GET and PUT operations
+   - `api-list.go`: Listing operations
+   - `api-stat.go`: Status/info operations
+
+2. **Credential Management**: The `pkg/credentials/` package provides various credential providers:
+   - Static credentials
+   - Environment variables (AWS/MinIO)
+   - IAM roles
+   - STS (Security Token Service) variants
+   - File-based credentials
+   - Chain provider for fallback mechanisms
+
+3. **Request Signing**: The `pkg/signer/` package handles AWS signature versions:
+   - V2 signatures (legacy)
+   - V4 signatures (standard)
+   - Streaming signatures for large uploads
+
+4. **Transport Layer**: Custom HTTP transport with:
+   - Retry logic with configurable max retries
+   - Health status monitoring
+   - Tracing support via httptrace
+   - Bucket location caching (`bucketLocCache`)
+   - Session caching for credentials
+
+5. **Helper Packages**:
+   - `pkg/encrypt/`: Server-side encryption utilities
+   - `pkg/notification/`: Event notification handling
+   - `pkg/policy/`: Bucket policy management
+   - `pkg/lifecycle/`: Object lifecycle rules
+   - `pkg/tags/`: Object and bucket tagging
+   - `pkg/s3utils/`: S3 utility functions
+   - `pkg/kvcache/`: Key-value caching
+   - `pkg/singleflight/`: Deduplication of concurrent requests
+
+### Testing Strategy
+- Unit tests alongside implementation files (`*_test.go`)
+- Comprehensive functional tests in `functional_tests.go` requiring a live MinIO server
+- Example programs in `examples/` directory demonstrating API usage
+- Build tag `//go:build mint` for integration tests
+
+### Error Handling
+- Custom error types in `api-error-response.go`
+- HTTP status code mapping
+- Retry logic for transient failures
+- Detailed error context preservation
+
+## Important Patterns
+
+1. **Context Usage**: All API methods accept `context.Context` for cancellation and timeout control
+2. **Options Pattern**: Methods use Options structs for optional parameters (e.g., `PutObjectOptions`, `GetObjectOptions`)
+3. **Streaming Support**: Large file operations use io.Reader/Writer interfaces for memory efficiency
+4. **Bucket Lookup Types**: Supports both path-style and virtual-host-style S3 URLs
+5. **MD5/SHA256 Hashing**: Configurable hash functions for integrity checks via `md5Hasher` and `sha256Hasher`