feat: add docs/ folder (architecture, guides, ADRs)

docs/decisions/adr-004-dual-mode-client.md

@@ -0,0 +1,18 @@
+# ADR-004: Dual-Mode Payload Client (Local + HTTP)
+
+## Status: Accepted
+
+## Context
+
+Apps need to access Payload CMS data. Payload 3.x offers both Local API (direct) and REST API (HTTP).
+
+## Decision
+
+`@repo/cms-client` supports both modes via `createPayloadClient()`.
+
+## Rationale
+
+- **Local mode (primary):** Direct Payload instance access — no HTTP overhead, full query capabilities (where, sort, limit, depth, page, populate). All server-side apps use this.
+- **HTTP mode (fallback):** REST API for external consumers without access to a Payload process.
+- Payload instance is injected at app startup, not imported — keeps cms-client standalone.
+- Both modes share the same `PayloadClient` interface — consumers don't know which mode is active.