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

docs/architecture/dependency-flow.md

@@ -0,0 +1,50 @@
+# Dependency Flow
+
+## Package Dependencies (one direction only)
+
+```
+apps/web-next          → @repo/api-client, @repo/ui
+                         Startup: @repo/cms-core (config) + @repo/cms-client (init local)
+apps/web-tanstack      → @repo/api-client, @repo/ui
+                         Startup: @repo/cms-core (config) + @repo/cms-client (init local)
+apps/cms               → @repo/cms-core, payload, next
+apps/storybook         → @repo/ui
+
+@repo/api-client       → @repo/api (router types only)
+@repo/api              → @repo/core/interface-adapters (controllers)
+@repo/cms-core         → @repo/core/application (use cases for hooks), payload (types)
+@repo/cms-client       → (standalone — receives Payload instance, doesn't import it)
+@repo/ui               → (standalone — tailwind, shadcn)
+```
+
+## Core Internal Dependencies
+
+```
+core/entities           → (standalone — zero deps)
+core/application        → core/entities only
+core/interface-adapters → core/application, core/entities
+core/infrastructure     → core/application, core/entities, @repo/cms-client, external libs
+core/di                 → all internal layers
+```
+
+## Circular Dependency Prevention — HARD RULES
+
+- **NEVER:** packages/core → apps/*
+- **NEVER:** apps/cms → packages/core/infrastructure
+- **NEVER:** packages/cms-client → apps/cms or packages/core or packages/cms-core
+- **NEVER:** packages/cms-core → packages/cms-client
+- **NEVER:** core/entities → anything
+- **NEVER:** core/application → core/infrastructure
+
+## Why These Rules Exist
+
+The Payload CMS integration creates a potential circular dependency:
+```
+apps/cms hooks → @repo/core/application (use cases)
+@repo/core/infrastructure → @repo/cms-client → Payload API
+```
+
+This is resolved by:
+1. `cms-client` is standalone — receives Payload instance via injection, never imports it
+2. `cms-core` hooks only import from `core/application`, never `core/infrastructure`
+3. App startup code (not a shared package) wires Payload instance into cms-client