docs: add project-specific engineering decisions and evidence policy

docs/engineering-decisions.md

@@ -0,0 +1,23 @@
+# Engineering Decisions & Trade-offs
+
+## End-to-end system story
+TrojanChat should be evaluated as a complete interaction pipeline: user input, prompt/context construction, model invocation, response handling, observability, and user-facing delivery.
+
+## Key trade-offs
+- **Context depth vs. latency and cost:** Larger context windows can improve continuity while increasing inference time and token usage.
+- **Helpfulness vs. hallucination risk:** More open-ended generation can feel useful but requires stronger grounding, validation, and failure handling.
+- **Feature breadth vs. reliability:** Additional tools and integrations expand capability while increasing the number of dependencies and failure modes.
+- **Convenience vs. privacy:** Conversation logging and analytics improve debugging but require explicit data-handling boundaries.
+
+## Failure modes to test
+- Provider timeouts, rate limits, and malformed responses
+- Missing or invalid credentials
+- Oversized context and token-budget exhaustion
+- Unsafe, unsupported, or fabricated answers
+- Partial failures in logging, retrieval, or downstream integrations
+
+## Evidence policy
+Only measured results should be described as completed. Targets, demonstrations, simulations, and planned capabilities must be labeled clearly. Evaluation reports should record model/provider version, environment, test cases, sample count, methodology, and limitations.
+
+## Clean-clone validation
+A reviewer should be able to clone the repository, configure documented environment variables, run tests, and start a representative local or demo path without undocumented files or manual patches.