Add purpose and feature surface mapping reports for repository

reports/README.md

@@ -0,0 +1,130 @@
+# Reports Directory
+
+This directory contains automated analysis and mapping reports for the Sherlock Multiagent Data Scientist platform.
+
+## Files
+
+### `purpose-map.md`
+**Human-readable purpose and surface mapping document**
+
+Contains:
+- Single-sentence MVP purpose statement
+- Feature & User Journey Mapping table with 7 journeys
+  - Journey description
+  - Primary files involved
+  - Entry commands
+  - Data dependencies
+  - Risk assessment (H/M/L)
+- Runnable surfaces documentation
+  - Core services with entrypoints
+  - Infrastructure dependencies
+  - Docker deployment options
+  - Scripts and utilities
+- Data dependencies & flow diagram
+- Risk assessment summary
+- Assumptions & uncertainties
+
+### `feature-surface.json`
+**Machine-readable feature surface mapping**
+
+Structured JSON containing:
+- Repository metadata
+- 7 features with detailed specifications:
+  - Endpoints (methods, paths, services, ports)
+  - Entry commands
+  - Data dependencies
+  - Risk levels and notes
+- Runnable surfaces:
+  - 6 services (FastAPI, React SPA, MCP protocol)
+  - 4 infrastructure components (MongoDB, Redis, Kafka, Nginx)
+  - Docker deployment configurations
+  - Utility scripts
+- Data flow and storage architecture
+- Configuration details
+- Risk summary
+- Assumptions (15% uncertainty)
+- Identified uncertainties
+
+## Generation Details
+
+- **Generated**: 2025-10-13
+- **Generator**: A0 Purpose & Surface Mapper
+- **Repository Version**: 2.1.0
+- **Uncertainty Level**: 15%
+
+## Usage
+
+### View Human-Readable Report
+```bash
+cat reports/purpose-map.md
+```
+
+### Parse Machine-Readable JSON
+```python
+import json
+
+with open('reports/feature-surface.json') as f:
+    data = json.load(f)
+
+# Access features
+for feature in data['features']:
+    print(f"{feature['name']}: {feature['risk_level']} risk")
+
+# Access services
+for service in data['runnable_surfaces']['services']:
+    print(f"{service['name']} on port {service['port']}")
+```
+
+### Quick Stats
+```bash
+# Validate JSON
+python -m json.tool reports/feature-surface.json > /dev/null && echo "✓ Valid JSON"
+
+# Count features
+python -c "import json; print(f\"{len(json.load(open('reports/feature-surface.json'))['features'])} features mapped\")"
+
+# Line counts
+wc -l reports/*
+```
+
+## Key Findings
+
+### MVP Purpose
+Sherlock is an **end-to-end, orchestrator-driven data science platform** that enables users to perform exploratory data analysis, data quality validation, feature engineering, and model training through microservices agents coordinated by a master orchestrator with real-time observability.
+
+### Architecture
+- **Type**: Microservices
+- **Services**: 6 (Master Orchestrator, EDA, Refinery, ML, MCP, Dashboard)
+- **Infrastructure**: MongoDB, Redis, Kafka, Nginx
+- **License**: Hybrid (Apache 2.0 for clients, BUSL 1.1 for server)
+
+### Risk Distribution
+- **High**: 1 feature (Model Training)
+- **Medium**: 5 features (Upload, EDA, Feature Eng, Orchestration, Dashboard)
+- **Low**: 1 feature (Data Quality)
+
+### Deployment
+Multiple options:
+1. Individual services: `python start_<service>.py`
+2. Docker Compose: `docker-compose up -d`
+3. Production: `python production_deployment.py`
+
+## Assumptions
+
+1. Primary use case: Data scientists performing end-to-end analysis workflows
+2. Deployment: Single-node or small-cluster with Docker Compose
+3. Data scale: Up to 100k rows (configurable)
+4. Concurrency: 1 workflow at a time (configurable)
+5. Mode: Development (production has API key support)
+
+## Identified Uncertainties
+
+1. Mission Definition Module (mentioned but not implemented)
+2. Data Governance enforcement details
+3. Kafka/MongoDB fallback behavior
+4. Multi-tenant support (roadmap item)
+5. Hybrid API/LLM integration completeness
+
+---
+
+*For questions about these reports, refer to the problem statement that generated them or examine the source documentation in `/docs`, `README.md`, and agent files in `/mcp-server`.*