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

docs/decisions/adr-002-di-framework.md

@@ -0,0 +1,26 @@
+# ADR-002: InversifyJS for Dependency Injection
+
+## Status: Accepted
+
+## Context
+
+Need DI for clean architecture. Options: InversifyJS, tsyringe, manual composition root.
+
+## Decision
+
+InversifyJS with symbol-based resolution + targeted agent documentation.
+
+## Rationale
+
+- Scales to 20+ services with automatic dependency chain resolution
+- Built-in singleton/transient/request scopes
+- Middleware support for logging/tracing (Sentry integration)
+- Matches the reference implementation by Lazar Nikolov
+- Agent readability gap (4/10 → 7/10) mitigated by resolution tables and step-by-step recipes in di/AGENTS.md
+- Familiar to developers from Java/C# backgrounds
+
+## Trade-offs
+
+- Requires reflect-metadata + decorator config in tsconfig
+- Symbol indirection harder to trace than plain functions
+- Extra dependency (inversify + reflect-metadata)