feat: add Technical Depth Scale (1-5) replacing binary DEVELOPER_MODE

README.md

@@ -406,7 +406,10 @@ http://localhost:3000/api
 
 #### Messages
 - `POST /api/conversations/:uuid/messages` - Create user message
-- `POST /api/messages/:uuid/generate` - Generate AI response
+- `POST /api/messages/:uuid/generate` - Generate AI response (accepts optional `technical_depth` 1-5)
+
+#### Technical Depth
+- `GET /api/depth-levels` - List available technical depth levels (public, no auth)
 
 #### Knowledge Base
 - `POST /api/knowledge/items` - Create knowledge item (supports raw content, pre-chunked data, or chunks with embeddings)
@@ -531,6 +534,53 @@ curl -X POST /api/messages/msg456/generate \
 # Response: {"uuid": "msg789", "content": "To integrate our API...", ...}
 ```
 
+## 🎚️ Technical Depth Scale
+
+Control how technical the assistant's responses are with a single integer parameter (1-5). This replaces the binary `DEVELOPER_MODE` and provides granular control.
+
+| Level | Audience | Code Snippets | Response Style |
+|-------|----------|---------------|----------------|
+| 1 | Executive / Sales | Never | Business language, impact-focused |
+| 2 | Support / Product | Never | User-facing behavior, simplified terms |
+| 3 | Mixed / General | Minimal | Balanced (default) |
+| 4 | Technical / QA | Yes | Implementation details, code references |
+| 5 | Developer | Full | Deep dive with code, paths, commands |
+
+### Configuration Priority (highest wins)
+
+1. **Per-request** - Pass `technical_depth` in `POST /api/messages/:uuid/generate` body
+2. **Per-conversation** - Set `technical_depth` when creating a conversation
+3. **Company default** - Set via `PUT /api/companies/:companyUuid/ai-settings`
+4. **DEVELOPER_MODE fallback** - `true` maps to 5, `false` maps to 2
+5. **Global default** - 3 (or `TECHNICAL_DEPTH_DEFAULT` env var)
+
+### Usage Examples
+
+```bash
+# Create conversation with depth level
+curl -X POST /api/conversations \
+  -H "Content-Type: application/json" \
+  -d '{"title": "Executive Brief", "technical_depth": 1}'
+
+# Override depth per-request
+curl -X POST /api/messages/$MSG_UUID/generate \
+  -H "Content-Type: application/json" \
+  -d '{"technical_depth": 5}'
+
+# Set company default
+curl -X PUT /api/companies/$COMPANY_UUID/ai-settings \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"technical_depth": 3}'
+
+# List available levels
+curl /api/depth-levels
+```
+
+### Backward Compatibility
+
+`DEVELOPER_MODE` continues to work as a fallback when `technical_depth` is not configured at any level. Setting `technical_depth` at any level takes precedence.
+
 ## 🗄️ Database Setup
 
 ### Option A: Run Migrations (Recommended)

env.example

@@ -62,7 +62,17 @@ SLACK_SIGNING_SECRET=your-slack-signing-secret
 # Enables LLM-as-Judge for context validation (requires OPENAI_API_KEY)
 AI_VALIDATION_ENABLED=false
 
-# Developer Mode (Optional)
+# Developer Mode (Optional - Legacy, superseded by Technical Depth)
 # true = Strict code grounding (for developers/PMs querying codebase)
 # false = Friendly generic responses (for end users)
+# Only used as fallback if technical_depth is not configured at any level
 DEVELOPER_MODE=true
+
+# Technical Depth (Optional)
+# Global default for technical depth level (1-5) when not set per-company or per-conversation
+# 1 = Executive (no code, business language)
+# 2 = Support (no code, simplified terms)
+# 3 = General (balanced, default)
+# 4 = Technical (code excerpts, implementation details)
+# 5 = Developer (full code, deep implementation detail)
+# TECHNICAL_DEPTH_DEFAULT=3

jest.config.ts

@@ -0,0 +1,15 @@
+import type { Config } from 'jest';
+
+const config: Config = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/src'],
+  testMatch: ['**/__tests__/**/*.test.ts'],
+  moduleFileExtensions: ['ts', 'js', 'json'],
+  collectCoverageFrom: [
+    'src/services/depth-*.ts',
+    '!src/**/*.d.ts'
+  ]
+};
+
+export default config;