updated documentation for semantic and constant refactor

docs/services/shared.md

@@ -1,18 +1,67 @@
 # Shared Package
 
-**Package:** '@nexusai/shared'
-**Location:** 'packages/shared'
+**Package:** `@nexusai/shared`  
+**Location:** `packages/shared`
 
 ## Purpose
-Common utilities and configuration used across all NexusAI services
-Keeping these here avoids duplicating and ensure consistent behavior
 
-# Exports
+Common utilities and configuration used across all NexusAI services.
+Keeping these here avoids duplication and ensures consistent behaviour.
 
-### 'getEnv(key, defaultValue?)'
-Loads an environment variable by key.  If no default is provided and the variable is missing, throws at startup rather than failing later on.
-```javascript
+## Exports
+
+### `getEnv(key, defaultValue?)`
+
+Loads an environment variable by key. If no default is provided and the
+variable is missing, throws at startup rather than failing silently later.
+
+```js
 const { getEnv } = require('@nexusai/shared');
-const PORT = getEnv('PORT', '3002');         // optional — falls back to 3002
-const DB   = getEnv('SQLITE_PATH');          // required — throws if missing
+
+const PORT = getEnv('PORT', '3002');   // optional — falls back to 3002
+const DB   = getEnv('SQLITE_PATH');    // required — throws if missing
 ```
+
+---
+
+### Constants
+
+Tuneable values and shared identifiers are centralised in `constants.js`
+rather than hardcoded across services. Import the relevant group by name.
+
+```js
+const { QDRANT, COLLECTIONS, EPISODIC } = require('@nexusai/shared');
+```
+
+#### `QDRANT`
+
+Vector store configuration. Values here must stay in sync with the
+embedding model and Qdrant collection setup.
+
+| Key | Value | Description |
+|---|---|---|
+| `DEFAULT_URL` | `http://localhost:6333` | Fallback Qdrant URL if `QDRANT_URL` env var is not set |
+| `VECTOR_SIZE` | `768` | Output dimensions of `nomic-embed-text` |
+| `DISTANCE_METRIC` | `'Cosine'` | Similarity metric used for all collections |
+| `DEFAULT_LIMIT` | `10` | Default top-k for vector searches |
+
+#### `COLLECTIONS`
+
+Canonical Qdrant collection names. Used by both the semantic layer and
+any service that constructs Qdrant queries directly.
+
+| Key | Value |
+|---|---|
+| `EPISODES` | `'episodes'` |
+| `ENTITIES` | `'entities'` |
+| `SUMMARIES` | `'summaries'` |
+
+#### `EPISODIC`
+
+Default pagination and result limits for SQLite episode queries.
+
+| Key | Value | Description |
+|---|---|---|
+| `DEFAULT_RECENT_LIMIT` | `10` | Default number of recent episodes to retrieve |
+| `DEFAULT_PAGE_SIZE` | `20` | Default episodes per page for paginated queries |
+| `DEFAULT_SEARCH_LIMIT` | `10` | Default number of FTS search results to return |