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

docs/decisions/adr-005-atomic-design.md

@@ -0,0 +1,20 @@
+# ADR-005: Atomic Design for UI Components
+
+## Status: Accepted
+
+## Context
+
+Need a scalable component architecture for the shared UI package.
+
+## Decision
+
+Atomic Design (atoms/molecules/organisms/templates) + shadcn/ui + Storybook.
+
+## Rationale
+
+- Clear hierarchy makes agents know exactly where to place new components
+- Import rules enforce composition direction (atoms never import molecules)
+- Co-located stories make components self-documenting
+- shadcn/ui provides excellent base atoms that map naturally to atomic levels
+- Storybook sidebar mirrors the hierarchy via story titles
+- Pages live in apps (not UI package) — they connect to real data