feat(docs): Add comprehensive documentation for AGENTS architecture

- Introduced detailed documentation for the AGENTS SDK, covering the overall structure, conventions, and anti-patterns across various layers: core library utilities, models, and services.
- Included guidelines for error handling, async operations, and testing practices to ensure consistency and best practices in development.
- Enhanced the documentation with clear examples and a structured overview to facilitate understanding and usage of the SDK.

These additions improve the clarity and usability of the AGENTS SDK for developers.

Author: Palbahngmiyine

AGENTS.md

@@ -0,0 +1,93 @@
+# SOLAPI SDK for Node.js
+
+**Generated:** 2026-01-21
+**Commit:** 9df35df
+**Branch:** master
+
+## OVERVIEW
+
+Server-side SDK for SMS/LMS/MMS and Kakao messaging in Korea. Uses Effect library for type-safe functional programming with Data.TaggedError-based error handling.
+
+## STRUCTURE
+
+```
+solapi-nodejs/
+├── src/
+│   ├── index.ts              # SolapiMessageService facade (entry point)
+│   ├── errors/               # Data.TaggedError types
+│   ├── lib/                  # Core utilities (fetcher, auth, error handler)
+│   ├── models/               # Schemas, requests, responses (see models/AGENTS.md)
+│   ├── services/             # Domain services (see services/AGENTS.md)
+│   └── types/                # Shared type definitions
+├── test/                     # Mirrors src/ structure
+├── examples/                 # Usage examples (excluded from build)
+└── debug/                    # Debug scripts
+```
+
+## WHERE TO LOOK
+
+| Task | Location | Notes |
+|------|----------|-------|
+| Add new message type | `src/models/base/messages/` | Extend MessageType union |
+| Add new service | `src/services/` | Extend DefaultService |
+| Add new error type | `src/errors/defaultError.ts` | Extend Data.TaggedError |
+| Add utility function | `src/lib/` | Follow Effect patterns |
+| Add Kakao BMS type | `src/models/base/kakao/bms/` | Add to BMS_REQUIRED_FIELDS |
+| Fix API request issue | `src/lib/defaultFetcher.ts` | HTTP client with retry |
+| Understand error flow | `src/lib/effectErrorHandler.ts` | Effect → Promise conversion |
+
+## CONVENTIONS
+
+**Effect Library (MANDATORY)**:
+- All errors: `Data.TaggedError` with environment-aware `toString()`
+- Async operations: `Effect.gen` + `Effect.tryPromise`, never wrap with try-catch
+- Validation: `Effect Schema` with `Schema.filter`, `Schema.transform`
+- Error execution: `runSafePromise()` / `runSafeSync()` from effectErrorHandler
+
+**TypeScript**:
+- **NEVER use `any`** — use `unknown` + type guards or Effect Schema
+- Strict mode enforced (`noUnusedLocals`, `noUnusedParameters`)
+- Path aliases: `@models`, `@lib`, `@services`, `@errors`, `@internal-types`
+
+**Testing**:
+- Unit: `vitest` with `Schema.decodeUnknownEither()` for validation tests
+- E2E: `@effect/vitest` with `it.effect()` and `Effect.gen`
+- Run: `pnpm test` / `pnpm test:watch`
+
+## ANTI-PATTERNS
+
+| Pattern | Why Bad | Do Instead |
+|---------|---------|------------|
+| `any` type | Loses type safety | `unknown` + type guards |
+| `as any`, `@ts-ignore` | Suppresses errors | Fix the type issue |
+| try-catch around Effect | Loses Effect benefits | Use `Effect.catchTag` |
+| Direct `throw new Error()` | Inconsistent error handling | Use `Data.TaggedError` |
+| Empty catch blocks | Swallows errors | Handle or propagate |
+
+## COMMANDS
+
+```bash
+pnpm dev          # Watch mode (tsup)
+pnpm build        # Lint + build
+pnpm lint         # Biome check with auto-fix
+pnpm test         # Run tests once
+pnpm test:watch   # Watch mode
+pnpm docs         # Generate TypeDoc
+```
+
+## ARCHITECTURE NOTES
+
+**Service Facade Pattern**: `SolapiMessageService` aggregates 7 domain services via `bindServices()` dynamic method binding. All services extend `DefaultService`.
+
+**Error Flow**:
+```
+API Response
+  → defaultFetcher (creates Effect errors)
+  → runSafePromise (converts to Promise)
+  → toCompatibleError (preserves properties on Error)
+  → Consumer
+```
+
+**Production vs Development**: Error messages stripped of stack traces and detailed context in production (`process.env.NODE_ENV === 'production'`).
+
+**Retry Logic**: `defaultFetcher.ts` implements 3x retry with exponential backoff for retryable errors (connection refused, reset, 503).

src/lib/AGENTS.md

@@ -0,0 +1,63 @@
+# Core Library Utilities
+
+## OVERVIEW
+
+Cross-cutting utilities used by all services. Effect-based async handling and error management.
+
+## STRUCTURE
+
+```
+lib/
+├── defaultFetcher.ts        # HTTP client with Effect.gen, retry, Match
+├── effectErrorHandler.ts    # runSafePromise, toCompatibleError, formatError
+├── authenticator.ts         # HMAC-SHA256 auth header generation
+├── stringifyQuery.ts        # URL query string builder
+├── fileToBase64.ts          # File/URL → Base64 converter
+└── stringDateTrasnfer.ts    # Date parsing with InvalidDateError
+```
+
+## WHERE TO LOOK
+
+| Task | File | Notes |
+|------|------|-------|
+| HTTP request issues | `defaultFetcher.ts` | Retry logic, error handling |
+| Error formatting | `effectErrorHandler.ts` | Production vs dev messages |
+| Auth issues | `authenticator.ts` | HMAC signature generation |
+| Query params | `stringifyQuery.ts` | Array handling, encoding |
+| File handling | `fileToBase64.ts` | URL detection, Base64 encoding |
+| Date parsing | `stringDateTrasnfer.ts` | ISO format conversion |
+
+## CONVENTIONS
+
+**Effect.tryPromise for Async**:
+```typescript
+Effect.tryPromise({
+  try: () => fetch(url, options),
+  catch: e => new NetworkError({ url, cause: e }),
+});
+```
+
+**Effect.gen for Complex Flow**:
+```typescript
+Effect.gen(function* (_) {
+  const auth = yield* _(buildAuth(params));
+  const response = yield* _(fetchWithRetry(url, auth));
+  return yield* _(parseResponse(response));
+});
+```
+
+**Error to Promise Conversion**:
+```typescript
+// Always use runSafePromise for Effect → Promise
+return runSafePromise(effect);
+
+// Never wrap Effect with try-catch
+// BAD: try { await Effect.runPromise(...) } catch { }
+```
+
+## ANTI-PATTERNS
+
+- Don't bypass `runSafePromise` — loses error formatting
+- Don't use try-catch around Effect — use Effect.catchTag
+- Don't create new HTTP client — use defaultFetcher
+- Don't hardcode API URL — use DefaultService.baseUrl

src/models/AGENTS.md

@@ -0,0 +1,84 @@
+# Models Layer
+
+## OVERVIEW
+
+Three-layer model architecture using Effect Schema for runtime validation.
+
+## STRUCTURE
+
+```
+models/
+├── base/                       # Core domain entities
+│   ├── messages/message.ts     # MessageType, messageSchema
+│   ├── kakao/
+│   │   ├── kakaoOption.ts      # BMS validation, VariableValidationError
+│   │   ├── kakaoButton.ts      # Discriminated union (8 types)
+│   │   └── bms/                # 7 BMS chat bubble schemas
+│   ├── rcs/                    # RCS options and buttons
+│   └── naver/                  # Naver Talk Talk
+├── requests/                   # Input → API payload transformation
+│   ├── messages/               # Send, group, query requests
+│   ├── kakao/                  # Channel/template operations
+│   ├── iam/                    # Block list management
+│   └── common/datePayload.ts   # Shared date range type
+└── responses/                  # API response types (mostly type-only)
+```
+
+## WHERE TO LOOK
+
+| Task | Location | Notes |
+|------|----------|-------|
+| Add message type | `base/messages/message.ts` | Add to MessageType union |
+| Add BMS type | `base/kakao/bms/` + `kakaoOption.ts` | Update BMS_REQUIRED_FIELDS |
+| Add button variant | `base/kakao/kakaoButton.ts` | Discriminated union pattern |
+| Add request validation | `requests/` domain folder | Use Schema.transform |
+| Add response type | `responses/` domain folder | Type-only usually sufficient |
+
+## CONVENTIONS
+
+**Type + Schema + Class Pattern**:
+```typescript
+// 1. Type
+export type MyType = Schema.Schema.Type<typeof mySchema>;
+
+// 2. Schema
+export const mySchema = Schema.Struct({
+  field: Schema.String,
+  optional: Schema.optional(Schema.Number),
+});
+
+// 3. Class (optional, for runtime behavior)
+export class MyClass {
+  constructor(parameter: MyType) { /* ... */ }
+}
+```
+
+**Discriminated Union**:
+```typescript
+export const buttonSchema = Schema.Union(
+  webButtonSchema,      // { linkType: 'WL', ... }
+  appButtonSchema,      // { linkType: 'AL', ... }
+);
+```
+
+**Custom Validation**:
+```typescript
+Schema.String.pipe(
+  Schema.filter(isValid, { message: () => 'Error message' }),
+);
+```
+
+**Transform with Validation**:
+```typescript
+Schema.transform(Schema.String, Schema.String, {
+  decode: input => normalize(input),
+  encode: output => output,
+});
+```
+
+## ANTI-PATTERNS
+
+- Don't skip schema validation for user input
+- Don't use interfaces when schema needed — use Schema.Struct
+- Don't duplicate validation logic — compose schemas
+- Don't create class without schema — validate first

src/services/AGENTS.md

@@ -0,0 +1,67 @@
+# Services Layer
+
+## OVERVIEW
+
+Domain services extending `DefaultService` base class. Each service handles one API domain.
+
+## STRUCTURE
+
+```
+services/
+├── defaultService.ts           # Base class: auth, HTTP abstraction
+├── messages/
+│   ├── messageService.ts       # send(), sendOne(), getMessages()
+│   └── groupService.ts         # Group operations (create, add, send)
+├── kakao/
+│   ├── channels/               # Channel CRUD
+│   └── templates/              # Template CRUD with Effect.all
+├── cash/cashService.ts         # getBalance()
+├── iam/iamService.ts           # Block lists, 080 rejection
+└── storage/storageService.ts   # File uploads
+```
+
+## WHERE TO LOOK
+
+| Task | File | Notes |
+|------|------|-------|
+| Add new service | Create in domain folder | Extend DefaultService |
+| Modify HTTP behavior | `defaultService.ts` | Base URL, auth handling |
+| Complex Effect logic | `messageService.ts` | Reference for Effect.gen pattern |
+| Parallel processing | `kakaoTemplateService.ts` | Effect.all example |
+
+## CONVENTIONS
+
+**Service Pattern**:
+```typescript
+export default class MyService extends DefaultService {
+  constructor(apiKey: string, apiSecret: string) {
+    super(apiKey, apiSecret);
+  }
+  
+  async myMethod(data: Request): Promise<Response> {
+    return this.request<Request, Response>({
+      httpMethod: 'POST',
+      url: 'my/endpoint',
+      body: data,
+    });
+  }
+}
+```
+
+**Effect.gen Pattern** (for complex logic):
+```typescript
+async send(messages: Request): Promise<Response> {
+  const effect = Effect.gen(function* (_) {
+    const validated = yield* _(validateSchema(messages));
+    const response = yield* _(Effect.promise(() => this.request(...)));
+    return response;
+  });
+  return runSafePromise(effect);
+}
+```
+
+## ANTI-PATTERNS
+
+- Don't call `defaultFetcher` directly — use `this.request()`
+- Don't bypass schema validation — always validate input
+- Don't mix Effect and Promise styles — pick one per method